System.Diagnostics.Activity

Activity

public class Activity : IDisposable

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 suppressed, and the operation does something reasonable (typically doing nothing).

public static Activity Current { get; set; }

Gets or sets the current operation (Activity) for the current thread. This flows across async calls.

public static ActivityIdFormat DefaultIdFormat { get; set; }

Activity tries to use the same format for IDs as its parent. However if the activity has no parent, it has to do something. This determines the default format we use.

public static bool ForceDefaultIdFormat { get; set; }

Normally if the ParentID is defined, the format of that is used to determine the format used by the Activity. However if ForceDefaultFormat is set to true, the ID format will always be the DefaultIdFormat even if the ParentID is define and is a different format.

public static Func<ActivityTraceId> TraceIdGenerator { get; set; }

When starting an Activity which does not have a parent context, the Trace Id will automatically be generated using random numbers. TraceIdGenerator can be used to override the runtime's default Trace Id generation algorithm.

public ActivityTraceFlags ActivityTraceFlags { get; set; }

Return the flags (defined by the W3C ID specification) associated with the activity.

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 ActivityContext Context { get; }

Get the context of the activity. Context becomes valid only if the activity has been started. otherwise will default context.

public string DisplayName { get; set; }

Gets or sets the display name of the Activity

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 IEnumerable<ActivityEvent> Events { get; }

Events is the list of all ActivityEvent objects attached to this Activity object. If there is not any ActivityEvent object attached to the Activity object, Events will return empty list.

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 ActivityIdFormat IdFormat { get; }

Returns the format for the ID.

public bool IsAllDataRequested { get; set; }

Indicate if the this Activity object should be populated with all the propagation info and also all other properties such as Links, Tags, and Events.

public ActivityKind Kind { get; }

Gets the relationship between the Activity, its parents, and its children in a Trace.

public IEnumerable<ActivityLink> Links { get; }

Links is the list of all ActivityLink objects attached to this Activity object. If there is no any ActivityLink object attached to the Activity object, Links will return empty list.

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 ActivitySpanId ParentSpanId { get; }

If the parent Activity ID has the W3C format, this returns the ID for the SpanId part of the ParentId. Otherwise it returns a zero SpanId.

public bool Recorded { get; }

True if the W3CIdFlags.Recorded flag is set.

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 ActivitySource Source { get; }

Get the ActivitySource object associated with this Activity.

public ActivitySpanId SpanId { get; }

If the Activity has the W3C format, this returns the ID for the SPAN part of the Id. Otherwise it returns a zero SpanId.

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 ActivityStatusCode Status { get; }

Gets status code of the current activity object.

public string StatusDescription { get; }

Gets the status description of the current activity object.

public IEnumerable<KeyValuePair<string, object>> TagObjects { get; }

List of the tags which 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 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 ActivityTraceId TraceId { get; }

If the Activity has the W3C format, this returns the ID for the TraceId part of the Id. Otherwise it returns a zero TraceId.

public string TraceStateString { get; set; }

Holds the W3C 'tracestate' header as a string. Tracestate is intended to carry information supplemental to trace identity contained in traceparent. List of key value pairs carried by tracestate convey information about request position in multiple distributed tracing graphs. It is typically used by distributed tracing systems and should not be used as a general purpose baggage as this use may break correlation of a distributed trace. Logically it is just a kind of baggage (if flows just like baggage), but because it is expected to be special cased (it has its own HTTP header), it is more convenient/efficient if it is not lumped in with other baggage.

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 AddEvent(ActivityEvent e)

Add ActivityEvent object to the Events list.

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 Activity AddTag(string key, object value)

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

public void Dispose()

Dispose will stop the Activity if it is already started and notify any event listeners. Nothing will happen otherwise.

protected virtual void Dispose(bool disposing)

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 object GetCustomProperty(string propertyName)

GetCustomProperty retrieve previously attached object mapped to the property name.

public object GetTagItem(string key)

Returns the value of the Activity tag mapped to the input key/>. Returns null if that key does not exist.

public Activity SetBaggage(string key, string value)

Add or update the Activity baggage with the input key and value. If the input value is null - if the collection has any baggage with the same key, then this baggage will get removed from the collection. - otherwise, nothing will happen and the collection will not change. If the input value is not null - if the collection has any baggage with the same key, then the value mapped to this key will get updated with the new input value. - otherwise, the key and value will get added as a new baggage to the collection.

public void SetCustomProperty(string propertyName, object propertyValue)

SetCustomProperty allow attaching any custom object to this Activity object. If the property name was previously associated with other object, SetCustomProperty will update to use the new propert value instead.

public Activity SetEndTime(DateTime endTimeUtc)

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

public Activity SetIdFormat(ActivityIdFormat format)

Sets IdFormat on the Activity before it is started. It takes precedence over Parent.IdFormat, ParentId format, DefaultIdFormat and ForceDefaultIdFormat.

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 SetParentId(ActivityTraceId traceId, ActivitySpanId spanId, ActivityTraceFlags activityTraceFlags = 0)

Set the parent ID using the W3C convention using a TraceId and a SpanId. This constructor has the advantage that no string manipulation is needed to set the ID.

public Activity SetStartTime(DateTime startTimeUtc)

Update the Activity to set start time

public Activity SetStatus(ActivityStatusCode code, string description = null)

Sets the status code and description on the current activity object.

public Activity SetTag(string key, object value)

Add or update the Activity tag with the input key and value. If the input value is null - if the collection has any tag with the same key, then this tag will get removed from the collection. - otherwise, nothing will happen and the collection will not change. If the input value is not null - if the collection has any tag with the same key, then the value mapped to this key will get updated with the new input value. - otherwise, the key and value will get added as a new tag to the collection.

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.