Diagnostics Options

Diagnostics options

The Diagnostics middleware read two option records: RequestTracingOptions<TRequest, TResponse> for the span and RequestMetricsOptions<TRequest, TResponse> for the metrics. Both are generic over the pipeline's request and response types, with TRequest : class.

For wiring and what the middleware emit, see Diagnostics. This page is the property reference.

Supplying options

Three paths, covered on Diagnostics: the configureTracing and configureMetrics parameters on AddPlumberDiagnostics, an inline Action<...> passed to a Use* method (takes precedence), or a Configure<RequestTracingOptions<TRequest, TResponse>>(...) registration resolved from the container as IOptions<T>. With none, the middleware run on the defaults below.

RequestTracingOptions

Configures the span the tracing middleware starts.

OperationName

string — default "Plumber.HandleRequest".

The name of the span. It becomes the Activity display name, the value tracing backends group and search by.

SpanKind

ActivityKind — default ActivityKind.Internal.

The kind of span. Set it to Server or Consumer when the pipeline sits at the edge of a service, so the span links correctly into a distributed trace.

AddDefaultAttributes

bool — default true.

When true, the middleware tags the span with request.id, request.type, request.elapsed_ms, and response.type. Set it to false to record only what you add through EnrichSpan.

EnrichSpan

Action<Activity, RequestContext<TRequest, TResponse>>? — default null.

Runs against the live Activity before the span closes, on both the success and failure paths. Use it to tag the span with request- and response-derived values:

options.EnrichSpan = (activity, context) =>
    activity.SetTag("tenant.id", context.Request.TenantId);

RecordException

bool — default true.

When true, a downstream exception sets the span status to Error and records the exception as a span event through Activity.AddException. Set it to false to leave the span status unset and add no event.

ThrowOnException

bool — default true.

When true, a downstream exception is recorded on the span and rethrown, so callers still see the failure. Set it to false to record the failure and swallow it. A cancellation is never recorded as an error either way — see Cancellation.

RequestMetricsOptions

Configures the instruments the metrics middleware records.

AddDefaultMetrics

bool — default true.

When true, the middleware records plumber.requests.count, plumber.requests.duration, and plumber.requests.errors, each tagged with request.type. Set it to false to record only what you add through RecordCustomMetrics.

RecordCustomMetrics

Action<RequestContext<TRequest, TResponse>, bool>? — default null.

Runs once per request in a finally, after the pipeline returns or throws. The bool reports whether the request succeeded, so you can record your own instruments alongside the defaults:

options.RecordCustomMetrics = (context, succeeded) =>
    myHistogram.Record(context.Elapsed.TotalMilliseconds,
        new KeyValuePair<string, object?>("succeeded", succeeded));

ThrowOnException

bool — default true.

When true, a downstream exception is recorded (the error counter increments) and rethrown. Set it to false to record the failure and swallow it — the pipeline completes as though it succeeded, which suits fire-and-forget consumers. A cancellation stays out of the error and duration metrics either way — see Cancellation.

See also

• Diagnostics — install, wiring, and what the middleware emit
• Request lifecycle — the RequestContext members enrichment reads from