Class SpanCapture

Namespace

TracingAssertions

Assembly

TracingAssertions.dll

Disposable, per-test capture of Activity spans emitted by one or more ActivitySources. Starts a raw ActivityListener sampling at AllDataAndRecorded and collects every stopped activity from the listened source(s). Disposing detaches the listener.

public sealed class SpanCapture : IDisposable

Inheritance

object

SpanCapture

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

SpanCaptureAssertions.HasNoSpan(SpanCapture, string)

SpanCaptureAssertions.HasSpan(SpanCapture, string)

SpanCaptureAssertions.HasSpanCount(SpanCapture, int)

Remarks

No OpenTelemetry SDK or exporter pipeline is involved: capture is a BCL ActivityListener over an ActivitySource matched by name, so the type is AOT-safe and carries no NuGet runtime dependency (System.Diagnostics.DiagnosticSource is in the shared framework).

Create one per test with a using statement for isolation; the listener stops collecting and detaches when disposed. The query helpers (FindByOperationName(string), FindByOperationNameAndTag(string, string, object), ChildrenOf(Activity)) read the captured set without advancing any clock.

Properties

Captured

The spans captured so far, in completion (activity-stopped) order. Each access returns a snapshot.

public IReadOnlyList<Activity> Captured { get; }

Property Value

IReadOnlyList<Activity>

Methods

ChildrenOf(Activity)

Returns the captured spans that are direct children of parent: a span whose ParentSpanId equals parent's SpanId and that shares its TraceId.

public IReadOnlyList<Activity> ChildrenOf(Activity parent)

Parameters

parent Activity

The parent span.

Returns

IReadOnlyList<Activity>

The direct children, in completion order (possibly empty).

Exceptions

ArgumentNullException

parent is null.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

FindByOperationName(string)

Returns the first captured span whose OperationName equals operationName (ordinal), or null if none matches.

public Activity? FindByOperationName(string operationName)

Parameters

operationName string

The operation name to look for.

Returns

Activity

The matching span, or null.

Exceptions

ArgumentNullException

operationName is null.

FindByOperationNameAndTag(string, string, object)

Returns the first captured span whose OperationName equals operationName and that carries a tag tagKey whose value matches tagValue, or null if none matches. Tag values are compared by their invariant ToString() form, matching how spans carry heterogeneously-typed tag values.

public Activity? FindByOperationNameAndTag(string operationName, string tagKey, object tagValue)

Parameters

operationName string

The operation name to look for.

tagKey string

The tag key to inspect.

tagValue object

The expected tag value (compared by invariant ToString).

Returns

Activity

The matching span, or null.

Exceptions

ArgumentNullException

operationName, tagKey, or tagValue is null.

ForSource(string)

Starts capturing spans from the single ActivitySource whose Name equals sourceName (ordinal), sampling at AllDataAndRecorded.

public static SpanCapture ForSource(string sourceName)

Parameters

sourceName string

The activity-source name to listen to.

Returns

SpanCapture

A disposable capture; dispose it (ideally via using) to detach the listener at the end of the test.

Exceptions

ArgumentNullException

sourceName is null.

ForSource(string, ActivitySamplingResult)

Starts capturing spans from the single ActivitySource whose Name equals sourceName (ordinal), at the given sampling result.

public static SpanCapture ForSource(string sourceName, ActivitySamplingResult sampling)

Parameters

sourceName string

The activity-source name to listen to.

sampling ActivitySamplingResult

The sampling result the listener returns for every activity.

Returns

SpanCapture

A disposable capture; dispose it (ideally via using) to detach the listener at the end of the test.

Remarks

The default ForSource(string) forces AllDataAndRecorded, so code that branches on IsAllDataRequested always takes the recorded path under test. Pass a lower result (for example PropagationData) to exercise the not-fully-sampled branch. Note that an activity's effective sampling is the maximum requested by any active listener, so this lower result only takes effect when the capture is the sole listener; a co-existing recording listener (for example an OpenTelemetry SDK pipeline) still raises the activity to fully recorded.

Exceptions

ArgumentNullException

sourceName is null.

ForSources(ActivitySamplingResult, params string[])

Starts capturing spans from any ActivitySource whose Name is one of sourceNames (ordinal), at the given sampling result (see ForSource(string, ActivitySamplingResult) for why this matters).

public static SpanCapture ForSources(ActivitySamplingResult sampling, params string[] sourceNames)

Parameters

sampling ActivitySamplingResult

The sampling result the listener returns for every activity.

sourceNames string[]

The activity-source names to listen to. An empty array captures nothing.

Returns

SpanCapture

A disposable capture; dispose it (ideally via using) to detach the listener at the end of the test.

Exceptions

ArgumentNullException

sourceNames is null.

ForSources(params string[])

Starts capturing spans from any ActivitySource whose Name is one of sourceNames (ordinal), sampling at AllDataAndRecorded.

public static SpanCapture ForSources(params string[] sourceNames)

Parameters

sourceNames string[]

The activity-source names to listen to. An empty array captures nothing.

Returns

SpanCapture

A disposable capture; dispose it (ideally via using) to detach the listener at the end of the test.

Exceptions

ArgumentNullException

sourceNames is null.