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.

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.

See also

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