DiagnosticSource.OnActivityImport(Activity, Object) Method

Definition

Namespace:

System.Diagnostics

Assembly:

System.Diagnostics.DiagnosticSource.dll

Source:

DiagnosticSourceActivity.cs

Transfers state to an activity from some event or operation, such as an incoming request, that occurred outside the process.

public:
 virtual void OnActivityImport(System::Diagnostics::Activity ^ activity, System::Object ^ payload);

public virtual void OnActivityImport (System.Diagnostics.Activity activity, object? payload);

abstract member OnActivityImport : System.Diagnostics.Activity * obj -> unit
override this.OnActivityImport : System.Diagnostics.Activity * obj -> unit

Public Overridable Sub OnActivityImport (activity As Activity, payload As Object)

Parameters

activity

Activity

The activity affected by an external event.

payload

Object

A payload that represents the incoming request.

Remarks

If an instrumentation site creates a new activity in response to some event outside the process, such as an incoming HTTP request), the OnActivityImport method allows that site will want to create a new activity and transfer state from the incoming request to the activity.

To the extent possible, this should be done by the instrumentation site, because there is a contract between the Activity and the incoming request logic at the instrumentation site. However, the instrumentation site can't handle policy. (For example, if sampling is done, exactly which requests should be sampled?) In these cases, the instrumentation site needs to call back out to the logging system and ask it to resolve policy (for example, to decide if the activity's "sampling" bit should be set). This is the purpose of the OnActivityImport method. It is given the activity as well as a payload object that represents the incoming request. The subscribers to the DiagnosticSource then have the opportunity to update this activity as desired.

This method is rarely used at instrumentation sites (only those sites that are on the boundary of the process), and the instrumetation site implements some default policy (it sets the activity in some way), and so it is not necessary to override this method if that default policy is fine. In other words, this method should be overridden in very rare (but often important) cases.

Note that payload is typed as Object here, but any particular instrumentation site and subscriber will know the type of the payload and thus cast and decode it if necessary.