AxisTelemetry 2.2.0

AxisTelemetry — Documentation

🌐 Português (documentação navegável)

Tracing and metrics for the Axis pipeline — IAxisTelemetry for spans, IAxisMetrics for counters and histograms, an OpenTelemetryAdapter over System.Diagnostics.ActivitySource + Meter, a NullAxisTelemetry for when you want telemetry off, and a TelemetryBehavior that wraps every mediator request with an AxisMediator.{RequestName} span plus duration / invocation / exception metrics.

using var span = telemetry.StartSpan("db.postgres.commit", AxisSpanKind.Client);
span.SetTag("db.system", "postgresql");
try
{
    await transaction.CommitAsync();
    span.SetStatus(AxisSpanStatus.Ok);
}
catch (Exception ex)
{
    span.RecordException(ex);
    throw;
}

Use this page as a map: read the trunk below (~5 min) and jump straight to the detail of the group you need — without reading hundreds of lines.

The trunk (read first)

The two interfaces in 60 seconds

public interface IAxisTelemetry
{
    IAxisSpan StartSpan(string operationName, AxisSpanKind kind = AxisSpanKind.Internal);
    string? CurrentTraceId { get; }
    string? CurrentSpanId { get; }
}

public interface IAxisMetrics
{
    void RecordHistogram(string name, double value, params KeyValuePair<string, object?>[] tags);
    void IncrementCounter(string name, long delta = 1, params KeyValuePair<string, object?>[] tags);
}

Tracing on one side, metrics on the other. The bundled OpenTelemetryAdapter implements both. → The contracts

IAxisSpan — the span you actually work with

public interface IAxisSpan : IDisposable
{
    string TraceId { get; }
    string SpanId { get; }
    IAxisSpan SetTag(string key, object? value);
    IAxisSpan SetStatus(AxisSpanStatus status, string? description = null);
    IAxisSpan RecordException(Exception exception);
    IAxisSpan AddEvent(string name, params KeyValuePair<string, object?>[] attributes);
}

Fluent — every mutator returns this. Dispose() ends the span. → Spans · IAxisSpan

TelemetryBehavior — auto-instrumentation of the mediator

Opt-in IAxisPipelineBehavior that opens an AxisMediator.{RequestName} span around every request, tags it with TraceId/JourneyId/RequestType/AxisEntityId/RequestName, times it, records:

• axis.handler.duration_ms (histogram)
• axis.handler.invocations (counter)
• axis.handler.exceptions (counter, on unhandled exceptions)

→ TelemetryBehavior — automatic instrumentation

Adapters

→ OpenTelemetry adapter · Azure Monitor adapter · Null adapter

Installation

dotnet add package AxisTelemetry

AxisTelemetry depends directly only on AxisLogger (which brings AxisResult and AxisMediator.Contracts transitively). The OpenTelemetry adapter uses System.Diagnostics.ActivitySource and System.Diagnostics.Metrics.Meter from the BCL — no extra NuGet packages.

Exporting to Azure Monitor / Application Insights? Install the pairing package instead:

dotnet add package AxisTelemetry.AzureMonitor

→ Azure Monitor adapter

→ Full guide: Getting started

The map (jump to what you need)

Start here: Getting started · The contracts · Why AxisTelemetry?

Fundamentals: Spans · IAxisSpan · TelemetryBehavior · OpenTelemetry adapter · Azure Monitor adapter

Reference & extras: Null adapter · Tag names · API reference

Design principles

1. Two narrow ports, one adapter. IAxisTelemetry for traces, IAxisMetrics for metrics; the OpenTelemetry adapter implements both with one type.
2. Vendor-neutral application code. ActivitySource and Meter live in the BCL; the application sees IAxisSpan only.
3. Pipeline-level instrumentation. Register TelemetryBehavior and every command/query is timed, tagged and traced — no per-handler boilerplate.
4. Null is a first-class adapter. NullAxisTelemetry.Instance lets tests and one-off tools skip the cost without changing the calling code.
5. Tag names are constants. TelemetryTagNames.RequestName (and friends) prevent typos and make sink-side queries predictable.

License

Apache 2.0