Class KevlarDiagnostics

Namespace: Kevlar

Assembly: Kevlar.dll

Names for Kevlar's built-in telemetry. On .NET 8+ targets every shield publishes counters and duration metrics; the shipped state gauges require .NET 10 or later. Metrics are published through a System.Diagnostics.Metrics.Meter named MeterName with zero configuration — subscribe with AddMeter("Kevlar") (OpenTelemetry) or a MeterListener. On netstandard2.0 the instruments are inert.

public static class KevlarDiagnostics

Inheritance: object

KevlarDiagnostics

Inherited Members: object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

The meter version is 1.0. Instruments:

kevlar.executions — completed public execution calls, including empty shields and pre-cancelled calls; attributes kevlar.shield.name, kevlar.execution.outcome (success/failure)
kevlar.retries — retry attempts; attribute kevlar.shield.name
kevlar.timeouts — executions cancelled by a timeout strategy, including delegates that complete after ignoring cancellation; attributes kevlar.shield.name and optional outcome (ignored)
kevlar.hedges — extra hedged attempts launched; attribute kevlar.shield.name
kevlar.hedge_attempts — completed attempts within hedged executions; attributes kevlar.shield.name and result (won/lost/cancelled/failed)
kevlar.fallbacks — outcomes replaced by a fallback; attribute kevlar.shield.name
kevlar.rejections — fail-fast rejections; attributes kevlar.shield.name, kevlar.rejection.type (circuit_open/rate_limit/rate_limiter_adapter/concurrency_limit)
kevlar.http.replay_suppressed — HTTP requests whose configured additional attempts were disabled for replay safety; attributes kevlar.shield.name and kevlar.suppression.reason
kevlar.circuit_breaker.transitions — circuit state changes; attributes kevlar.circuit_breaker.state.from, kevlar.circuit_breaker.state.to
kevlar.callback_errors — exceptions thrown by callbacks or cleanup operations; attributes kevlar.shield.name, kevlar.callback.kind, kevlar.callback.source
kevlar.execution.duration — execution duration histogram in seconds; attributes kevlar.shield.name, kevlar.execution.outcome
kevlar.strategy.events — strategy and custom events; attributes include shield, strategy, event, severity, attempt, exception type, and an optional bounded operation key
kevlar.attempt.duration — retry-attempt duration histogram in milliseconds with the strategy-event attributes
kevlar.circuit_breaker.state — current state gauge (closed=0, open=1, half_open=2, isolated=3)
kevlar.circuit_breaker.instances — circuit-breaker instance count grouped by current state
kevlar.concurrency_limit.inflight, kevlar.concurrency_limit.queued, and kevlar.concurrency_limit.capacity — concurrency-limit state gauges
kevlar.rate_limit.available and kevlar.rate_limit.queued — rate-limit state gauges

The kevlar.shield.name attribute is present only for shields named via WithName; an explicitly empty name is emitted as an empty tag value. State gauges also carry the bounded kevlar.strategy.index attribute so multiple stateful strategies in one pipeline remain distinct. Concurrency and rate measurements with the same name and strategy index are aggregated. Use kevlar.circuit_breaker.instances when several breakers share those attributes.

Fields

MeterName

The name of Kevlar's Meter.

public const string MeterName = "Kevlar"

Field Value

string

Methods

AddMetricEnricher(KevlarMetricEnricher)

Registers an application-defined enricher for every Kevlar metric measurement.

public static IDisposable AddMetricEnricher(KevlarMetricEnricher enricher)

Parameters

enricher KevlarMetricEnricher: The enricher to register.

Returns

IDisposable: A subscription that removes the enricher when disposed.

Remarks

Enrichers run synchronously only when an enabled instrument records or observes a measurement. Enricher exceptions are ignored and do not prevent later enrichers from running. Keep tag names and values bounded to avoid unbounded metric cardinality.

Listen(IKevlarTelemetryListener)

Subscribes a listener to synchronous strategy telemetry.

public static IDisposable Listen(IKevlarTelemetryListener listener)

Parameters

listener IKevlarTelemetryListener

Returns

IDisposable: A subscription that removes the listener when disposed.

ReportCallbackError(CallbackErrorKind, KevlarContext, Exception, string)

Reports a callback or cleanup failure without allowing diagnostics subscribers to affect execution. Custom strategies can use this method to follow Kevlar's isolation contract.

public static void ReportCallbackError(CallbackErrorKind kind, KevlarContext context, Exception exception, string source)

Parameters

kind CallbackErrorKind: The callback family that failed.
context KevlarContext: The active execution context.
exception Exception: The exception thrown by the callback.
source string: A stable callback or integration identifier.

Events

OnCallbackError

Raised when a strategy notification, observer, or superseded-result disposal throws. Each subscriber is isolated: subscriber failures are swallowed and do not prevent later subscribers from running. This event is process-global, not scoped to a shield or service provider; unsubscribe handlers when their lifetime ends.

public static event Action<CallbackErrorEvent>? OnCallbackError

Event Type

Action<CallbackErrorEvent>