Monitoring

DotNetWorkQueue emits metrics and traces through System.Diagnostics APIs. This page shows how to wire up observability for your queue application using OpenTelemetry.

For detailed reference, see:

• Metrics: all available metrics and instrument types
• Trace: all activity/span names and trace context propagation

Add the OpenTelemetry packages for your preferred exporters:

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

Wire up both metrics and tracing in one block:

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics =>
    {
        metrics.AddMeter("DotNetWorkQueue");
        metrics.AddPrometheusExporter();
    })
    .WithTracing(tracing =>
    {
        tracing.AddSource("dotnetworkqueue.instrumentationlibrary");
        tracing.AddOtlpExporter();   // or AddJaegerExporter(), AddZipkinExporter(), etc.
    });

var app = builder.Build();
app.MapPrometheusScrapingEndpoint();   // exposes GET /metrics for Prometheus
app.Run();

Note: DotNetWorkQueue does not ship any exporter packages. You choose your own: Prometheus, OTLP, Jaeger, Zipkin, Console, etc.

For console apps, Windows services, or other non-web hosts:

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("dotnetworkqueue.instrumentationlibrary")
    .AddOtlpExporter()
    .Build();

using var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddMeter("DotNetWorkQueue")
    .AddPrometheusHttpListener(options =>
    {
        options.UriPrefixes = new[] { "http://localhost:9464/" };
    })
    .Build();

// run your consumer/producer
// dispose providers on shutdown to flush pending telemetry

The samples repo includes a pre-built Grafana dashboard. It covers message throughput, handler duration, error and retry rates, heartbeat counters, serialization time, and message sizes.

To set it up:

1. Configure Prometheus to scrape your app's /metrics endpoint
2. Add the Prometheus data source in Grafana
3. Import grafana-dashboard.json from the samples repo root
4. Select your data source when prompted

See Metrics for the full Prometheus configuration and all available metric names.

Trace context propagates automatically from the producer to the consumer through message headers (W3C TraceContext format). You do not need to configure it.

The Dashboard provides a web UI and REST API for real-time queue monitoring (message counts, consumer tracking, job status, message history). It complements metrics and tracing. The dashboard shows the current state, and metrics and tracing show historical trends.