Class InstrumentCapture

Namespace

MetricsAssertions

Assembly

MetricsAssertions.dll

A single-instrument measurement capture, built on the first-party Microsoft.Extensions.Diagnostics.Metrics.Testing.MetricCollector<T> primitive (strongly typed, with built-in async waiting and an injectable TimeProvider). The generic value type is erased behind a uniform MeasurementSet surface so heterogeneous instruments share one assertion vocabulary and bundle into a MeterCapture.

Construct via Of<T>(Instrument<T>, TimeProvider?) (when the instrument is referenceable), OfObservable<T>(ObservableInstrument<T>, TimeProvider?), or OfName<T>(string, string, TimeProvider?) (by meter + instrument name - the primitive attaches even to a plain static Meter). For observable instruments, call RecordObservable() before reading. Dispose to release.

public sealed class InstrumentCapture : IDisposable

Inheritance

object

InstrumentCapture

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

InstrumentCaptureAssertions.HasCounterTotal(InstrumentCapture, long)

InstrumentCaptureAssertions.HasCounterTotalAtLeast(InstrumentCapture, long)

InstrumentCaptureAssertions.HasLastValue(InstrumentCapture, double)

InstrumentCaptureAssertions.HasLastValue(InstrumentCapture, double, double)

InstrumentCaptureAssertions.HasMeasurementCount(InstrumentCapture, int)

InstrumentCaptureAssertions.HasNoMeasurements(InstrumentCapture)

InstrumentCaptureAssertions.HasTaggedMeasurement(InstrumentCapture, string, object?)

InstrumentCaptureAssertions.HasUpDownCounterValue(InstrumentCapture, long)

Properties

Count

Gets how many measurements were captured.

public int Count { get; }

Property Value

int

InstrumentName

Gets the name of the captured instrument.

public string InstrumentName { get; }

Property Value

string

LastValue

Gets the most recent captured value, or null when none were captured.

public double? LastValue { get; }

Property Value

double?

Measurements

Gets a snapshot of every captured measurement as a queryable, assertable set.

public MeasurementSet Measurements { get; }

Property Value

MeasurementSet

Total

Gets the net total of all captured values (the running total of a counter / up-down counter).

public long Total { get; }

Property Value

long

Methods

Dispose()

Releases the underlying collector.

public void Dispose()

HasMeasurementTagged(string, object?)

Returns whether at least one captured measurement carries a tag key=value.

public bool HasMeasurementTagged(string key, object? value)

Parameters

key string

The tag key to match.

value object

The tag value to match.

Returns

bool

OfName<T>(object?, string, string, TimeProvider?)

Captures the instrument named instrumentName on the meter named meterName whose Scope equals meterScope. A meter created by an IMeterFactory carries the factory as its scope (the standard ASP.NET Core DI metrics path), so pass that factory here; a null scope only matches a meter created directly and would silently capture nothing from a factory-created meter.

public static InstrumentCapture OfName<T>(object? meterScope, string meterName, string instrumentName, TimeProvider? timeProvider = null) where T : struct

Parameters

meterScope object

The meter scope to match: the IMeterFactory instance for a DI-created meter, or null for a meter created directly.

meterName string

The meter name.

instrumentName string

The instrument name.

timeProvider TimeProvider

An optional clock for measurement timestamps and waits.

Returns

InstrumentCapture

Type Parameters

T

The instrument's value type.

OfName<T>(string, string, TimeProvider?)

Captures the instrument named instrumentName on the meter named meterName (no instrument reference required). The meter is matched with no scope, so this captures a meter created directly (new Meter(name)) but not one created by an IMeterFactory (whose meters carry a scope). For the DI path, use OfName<T>(object?, string, string, TimeProvider?).

public static InstrumentCapture OfName<T>(string meterName, string instrumentName, TimeProvider? timeProvider = null) where T : struct

Parameters

meterName string

The meter name.

instrumentName string

The instrument name.

timeProvider TimeProvider

An optional clock for measurement timestamps and waits.

Returns

InstrumentCapture

Type Parameters

T

The instrument's value type.

OfObservable<T>(ObservableInstrument<T>, TimeProvider?)

Captures the supplied (referenceable) observable instrument.

public static InstrumentCapture OfObservable<T>(ObservableInstrument<T> instrument, TimeProvider? timeProvider = null) where T : struct

Parameters

instrument ObservableInstrument<T>

The observable instrument to capture.

timeProvider TimeProvider

An optional clock for measurement timestamps and waits.

Returns

InstrumentCapture

Type Parameters

T

The instrument's value type.

Of<T>(Instrument<T>, TimeProvider?)

Captures the supplied (referenceable) instrument.

public static InstrumentCapture Of<T>(Instrument<T> instrument, TimeProvider? timeProvider = null) where T : struct

Parameters

instrument Instrument<T>

The instrument to capture.

timeProvider TimeProvider

An optional clock for measurement timestamps and waits.

Returns

InstrumentCapture

Type Parameters

T

The instrument's value type.

RecordObservable()

Pulls the current values of the instrument when it is observable (a gauge).

public void RecordObservable()

Since(MeasurementBaseline)

Returns only the measurements captured after baseline was taken.

public MeasurementSet Since(MeasurementBaseline baseline)

Parameters

baseline MeasurementBaseline

A baseline previously returned by this capture's Snapshot().

Returns

MeasurementSet

Exceptions

ArgumentException

baseline was taken from a different capture.

Snapshot()

Takes a baseline at the current point in the stream for a later Since(MeasurementBaseline) delta.

public MeasurementBaseline Snapshot()

Returns

MeasurementBaseline

Tagged(string, object?)

Returns the subset of captured measurements carrying a tag key=value.

public MeasurementSet Tagged(string key, object? value)

Parameters

key string

The tag key to match.

value object

The tag value to match.

Returns

MeasurementSet

WaitForAsync(int, CancellationToken)

Waits until at least count measurements have been captured.

public Task WaitForAsync(int count, CancellationToken cancellationToken = default)

Parameters

count int

The minimum number of measurements to wait for.

cancellationToken CancellationToken

A token to cancel the wait.

Returns

Task