Wicrypt.Telemetry.OpenTelemetry 1.0.3

Wicrypt.Telemetry.OpenTelemetry

An opinionated OpenTelemetry package for Wicrypt ASP.NET Core services. It configures:

• OTLP export for distributed traces and logs
• ASP.NET Core, HTTP client, Entity Framework Core, SQL Client, Redis, and runtime instrumentation
• Prometheus metrics at /metrics
• structured JSON console logs with trace correlation
• sampled HTTP request logs with sensitive-field redaction

Installation

dotnet add package Wicrypt.Telemetry.OpenTelemetry

Configuration

{
  "OpenTelemetry": {
    "Endpoint": "http://otel-collector:4317",
    "ServiceName": "Wicrypt.DeviceAPI"
  }
}

OpenTelemetry:Endpoint is required and must be an absolute OTLP/gRPC endpoint. ServiceName is optional; the entry assembly name is used when it is omitted. Sampling and request-logging behavior are code-level registration options rather than application configuration.

Usage

using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
using Wicrypt.Telemetry.OpenTelemetry;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.AddWicryptOpenTelemetry(openTelemetry =>
    openTelemetry
        .WithMetrics(metrics => metrics
            .AddMeter(FeeSettlementTelemetry.MeterName))
        .WithTracing(tracing => tracing
            .AddSource(MessageTelemetry.ActivitySourceName)));

WebApplication app = builder.Build();

app.MapOpenTelemetryMetrics();

app.Run();

Health endpoints under /health and the /metrics endpoint are excluded from request tracing and request logging.

The package does not assume application-specific meter or activity-source names. Each client registers its own sources through the configuration callback. The callback also accepts any other MeterProviderBuilder or TracerProviderBuilder customization supported by OpenTelemetry.

Log sampling

OTLP log export can be sampled independently for ordinary logs, custom events, and exception logs. Each percentage defaults to 100, preserving the package's existing behavior. Successful request logs have their own sampling percentage.

builder.AddWicryptOpenTelemetry(
    configure: openTelemetry => openTelemetry
        .WithTracing(tracing => tracing.AddSource("Wicrypt.Messages")),
    configureSampling: sampling =>
    {
        sampling.LogSamplingPercentage = 10;
        sampling.CustomEventSamplingPercentage = 100;
        sampling.ExceptionSamplingPercentage = 100;
    },
    configureRequestLogging: requestLogging =>
    {
        requestLogging.CaptureBodiesForSuccessfulRequests = false;
        requestLogging.SuccessfulRequestSamplingPercentage = 10;
    });

Each percentage is between 0 and 100; 0 disables successful request logs and 100 retains all of them. Failed requests are always logged with capturable JSON bodies. Exception records take precedence when a record could match more than one exported-log type. HTTP request logs are sampled only by the request-logging settings, avoiding a second round of sampling during OTLP export. Sampling affects only OTLP export—the structured console logger is unchanged.

Custom events

Inject ICustomTelemetryContext wherever a service needs to record a business event:

using Wicrypt.Telemetry.OpenTelemetry;

public sealed class CompletePaymentHandler(
    ICustomTelemetryContext telemetry)
{
    public Task HandleAsync(CancellationToken cancellationToken)
    {
        telemetry
            .SetProperty("flow.id", "flow-123")
            .AddCustomEvent(
                "payment.completed",
                new Dictionary<string, string>
                {
                    ["flow.id"] = "flow-123",
                    ["payment_intent"] = "WalletTopUp"
                });

        return Task.CompletedTask;
    }
}

AddCustomEvent adds an event to Activity.Current for trace correlation and writes a structured JSON information log for event queries. It still writes the log when no activity is active. Dots in log property names are normalized to underscores—for example, flow.id becomes flow_id—while span-event tag names are preserved.

The context is registered automatically by AddWicryptOpenTelemetry. Event names and properties belong to the client project; the package does not define business-specific event contracts.

Development

dotnet restore Wicrypt.Telemetry.OpenTelemetry.slnx
dotnet build Wicrypt.Telemetry.OpenTelemetry.slnx -c Release --no-restore
dotnet test Wicrypt.Telemetry.OpenTelemetry.slnx -c Release --no-build
dotnet pack src/Wicrypt.Telemetry.OpenTelemetry -c Release --no-build

Package versions are generated by Nerdbank.GitVersioning from version.json. The GitLab pipeline builds and tests every change, then packs and publishes main-branch changes to NuGet.org using NUGET_API_KEY.