System.Diagnostics.Activity

Activity

public class Activity

Activity represents operation with context to be used for logging. Activity has operation name, Id, start time and duration, tags and baggage. Current activity can be accessed with static AsyncLocal variable Activity.Current. Activities should be created with constructor, configured as necessary and then started with Activity.Start method which maintains parent-child relationships for the activities and sets Activity.Current. When activity is finished, it should be stopped with static Activity.Stop method. No methods on Activity allow exceptions to escape as a response to bad inputs. They are thrown and caught (that allows Debuggers and Monitors to see the error) but the exception is supressed, and the operation does something reasonable (typically doing nothing).

public static Activity Current { get; }

Returns the current operation (Activity) for the current thread. This flows across async calls.

public IEnumerable<KeyValuePair<string, string>> Baggage { get; }

Baggage is string-string key-value pairs that represent information that will be passed along to children of this activity. Baggage is serialized when requests leave the process (along with the ID). Typically Baggage is used to do fine-grained control over logging of the activity and any children. In general, if you are not using the data at runtime, you should be using Tags instead.

public TimeSpan Duration { get; }

If the Activity has ended ( Stop or SetEndTime was called) then this is the delta between StartTimeUtc and end. If Activity is not ended and SetEndTime was not called then this is Zero.

public string Id { get; }

This is an ID that is specific to a particular request. Filtering to a particular ID insures that you get only one request that matches. Id has a hierarchical structure: '|root-id.id1_id2.id3_' Id is generated when Start is called by appending suffix to Parent.Id or ParentId; Activity has no Id until it started

See for more details

public string OperationName { get; }

An operation name is a COARSEST name that is useful grouping/filtering. The name is typically a compile-time constant. Names of Rest APIs are reasonable, but arguments (e.g. specific accounts etc), should not be in the name but rather in the tags.

public Activity Parent { get; }

If the Activity that created this activity is from the same process you can get that Activity with Parent. However, this can be null if the Activity has no parent (a root activity) or if the Parent is from outside the process.

public string ParentId { get; }

If the parent for this activity comes from outside the process, the activity does not have a Parent Activity but MAY have a ParentId (which was deserialized from from the parent). This accessor fetches the parent ID if it exists at all. Note this can be null if this is a root Activity (it has no parent)

See for more details

public string RootId { get; }

Root Id is substring from Activity.Id (or ParentId) between '|' (or beginning) and first '.'. Filtering by root Id allows to find all Activities involved in operation processing. RootId may be null if Activity has neither ParentId nor Id. See for more details

public DateTime StartTimeUtc { get; }

The time that operation started. It will typically be initialized when Start is called, but you can set at any time via SetStartTime.

public IEnumerable<KeyValuePair<string, string>> Tags { get; }

Tags are string-string key-value pairs that represent information that will be logged along with the Activity to the logging system. This information however is NOT passed on to the children of this activity.

public Activity(string operationName)

Note that Activity has a 'builder' pattern, where you call the constructor, a number of 'Set*' and 'Add*' APIs and then call Start to build the activity. You MUST call Start before using it.

public Activity AddBaggage(string key, string value)

Update the Activity to have baggage with an additional 'key' and value 'value'. This shows up in the Baggage enumeration as well as the GetBaggageItem method. Baggage is meant for information that is needed for runtime control. For information that is simply useful to show up in the log with the activity use Tags. Returns 'this' for convenient chaining.

public Activity AddTag(string key, string value)

Update the Activity to have a tag with an additional 'key' and value 'value'. This shows up in the Tags enumeration. It is meant for information that is useful to log but not needed for runtime control (for the latter, Baggage)

public string GetBaggageItem(string key)

Returns the value of the key-value pair added to the activity with AddBaggage. Returns null if that key does not exist.

public Activity SetEndTime(DateTime endTimeUtc)

Update the Activity to set Duration as a difference between StartTimeUtc and endTimeUtc.

public Activity SetParentId(string parentId)

Updates the Activity To indicate that the activity with ID parentId caused this activity. This is intended to be used only at 'boundary' scenarios where an activity from another process logically started this activity. The Parent ID shows up the Tags (as well as the ParentID property), and can be used to reconstruct the causal tree. Returns 'this' for convenient chaining.

public Activity SetStartTime(DateTime startTimeUtc)

Update the Activity to set start time

public Activity Start()

Starts activity Sets Parent to hold Current.Sets Current to this activity.If StartTimeUtc was not set previously, sets it to UtcNow.Generates a unique Id for this activity. Use StartActivity to start activity and write start event.

public void Stop()

Stops activity: sets Current to Parent. If end time was not set previously, sets Duration as a difference between UtcNow and StartTimeUtc Use StopActivity to stop activity and write stop event.