Decode.Telemetry 2.1.0

Decode.Telemetry

OpenTelemetry instrumentation and extension methods for the Decode library ecosystem.

🚀 Features

• Decoupled & Standardized: Built on top of the native OpenTelemetry SDK for .NET.
• Unified Registration: Register tracing and metrics for the instrumented Decode libraries in a single call.
• Trace Support: Spans from Decode.Data (connections and transactions), Decode.Hosting (background worker cycles) and Decode.Security.Jwt (token generation and validation).
• Metrics Support: Counters for Decode.Security.Jwt token operations and Decode.Notifications business alerts.

Coverage. Three activity sources and two meters, listed in full below. The remaining packages — Decode.Storage.*, Decode.Email.* and Decode.AspNetCore — emit no telemetry of their own today; for HTTP spans use OpenTelemetry's AddAspNetCoreInstrumentation().

📦 Installation

dotnet add package Decode.Telemetry

🛠️ Setup

Register the instrumentation inside your Program.cs OpenTelemetry builder setup:

using Decode.Telemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddDecodeInstrumentation() // Decode.Data, Decode.Hosting and Decode.Security.Jwt sources
        .AddOtlpExporter())
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddDecodeInstrumentation() // Decode.Security.Jwt and Decode.Notifications meters
        .AddPrometheusExporter());

The two AddDecodeInstrumentation calls are distinct overloads — one on TracerProviderBuilder, one on MeterProviderBuilder — so both are needed. Registering only one silently drops the other half of the data.

📊 Telemetry Data Details

Traces

Activity source Decode.Data:

• DbSession.CreateConnection: Open operations on database connections.
• UnitOfWork.BeginTransaction: Transaction startup durations.
• UnitOfWork.Commit: Transaction commits.
• UnitOfWork.Rollback: Transaction rollbacks.

Activity source Decode.Security.Jwt:

• JwtService.CreateToken: JWT generation times.
• JwtService.ValidateToken: JWT validation times and internal validation status.

Activity source Decode.Hosting:

• {WorkerName}.Execute: one span per execution cycle of a ScopedPeriodicWorker, named after the worker type. Carries the tags worker.name and worker.execution_id (the same ExecutionId exposed on WorkerContext, so a span correlates with the worker's own log scope). On an unhandled exception the span status is set to Error with the exception message, whether or not WorkerOptions.SuppressExceptions lets the worker continue.

Metrics

The library exposes the following standard .NET Counters:

• decode.jwt.tokens.generated: Count of successfully generated tokens.
• decode.jwt.tokens.validated: Count of successfully validated tokens.
• decode.jwt.tokens.validation_failures: Count of token validation failures (includes a reason tag describing why, e.g., expired or invalid signature).
• decode.notifications.added: Count of Domain Notifications added in business logic (includes a key tag representing the field name and status_code for the HTTP response type).

🔎 Inspecting the registered names

The two sets are also exposed as public read-only lists, so the registration can be asserted instead of assumed:

IReadOnlyList<string> sources = OpenTelemetryExtensions.ActivitySourceNames;
IReadOnlyList<string> meters = OpenTelemetryExtensions.MeterNames;

They exist because the set is easy to get wrong by omission: Decode.Hosting was missing from the tracing registration before 2.0.0, which silently dropped every background worker span — nothing fails, the spans simply never arrive. Use them to pin the expected instrumentation in a test, or to wire a custom exporter without duplicating the string literals.

📄 License

MIT License.