YMJake.RocketMQ.OpenTelemetry 0.1.0

YMJake.RocketMQ.OpenTelemetry

OpenTelemetry registration for YMJake.RocketMQ, targeting .NET 10. The core client emits ActivitySource spans and Meter measurements using .NET APIs. This optional package registers them with application-owned OpenTelemetry providers.

using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

using var tracing = Sdk.CreateTracerProviderBuilder()
    .AddRocketMQInstrumentation()
    // Configure your exporter here, e.g. .AddOtlpExporter().
    .Build();

using var metrics = Sdk.CreateMeterProviderBuilder()
    .AddRocketMQInstrumentation()
    // Configure your exporter here, e.g. .AddOtlpExporter().
    .Build();

// Create and use Producer / SimpleConsumer / PushConsumer / Lite consumers normally.
// Dispose clients before the providers so final measurements can be exported.

Install your chosen exporter separately. Registration creates no background exporter, does not modify process-wide propagation delegates, and does not honor the proxy's metric endpoint or switch. Provider and exporter lifetime belongs to the application.

Tracing

Lite consumers reuse the same instrumentation. Simple consumers expose receive spans; application message processing after ReceiveAsync is outside the client's scope. Spans carry messaging system, operation, topic and client identifiers, plus the consumer group where applicable. Failures set Error status and error.type; message bodies, credentials, receipt handles and arbitrary user properties are not attached to spans.

The W3C traceparent and optional tracestate are injected into a publishing copy's user properties, matching the Java agent's propagation carrier. Existing propagation fields are preserved as a set, with case-insensitive detection; metadata supplied by the caller is not mutated. A Push process span uses the received producer context as its remote parent. Context is read from user properties only. Missing or malformed IDs start a root process span, independent of the worker's ambient activity. Baggage is not propagated. With no producer span, a W3C ambient activity can still be propagated. Generic route/heartbeat RPC instrumentation is not emitted.

Receive spans are created at completion with their original start time, only for a non-empty result or failure (including cancellation). Successful empty polls still record duration metrics. Receive spans use the caller's captured parent; process spans use the message producer parent, not the receive span. Each message with a valid propagated context contributes a receive Activity link, carrying its message ID. Messages sharing a producer span retain separate links; missing or malformed contexts are skipped. Links are supplied when the receive Activity starts so samplers can inspect them. Batch message count includes all received messages, including those without context. A batch remains one logical send span; per-message batch send spans are not implemented.

Each settlement attempt produces a Client-kind span with messaging.operation.type=settle. It uses the current application activity as parent, when present, and links the message's valid producer context. Push retry scheduling occurs outside these scopes: retries emit new attempts, while backoff waits emit no span or measurement. Push invisible-duration changes are named nack; explicit Simple/LiteSimple changes are named change_invisible_duration because callers may extend or shorten invisibility. Proxy-managed auto-renewal is not a client RPC and emits no separate span. Cancellation, invalid receipt handles and other rejected response statuses mark the individual attempt as failed without changing the client's exception or retry handling.

Metrics

Tags are topic, client_id, invocation_status (success / failure), and consumer_group for consumers. Settlement measurements also carry operation with one of the four fixed settlement names above. Avoid unbounded topic/group names when collecting metrics. Cancellation counts as failure. A listener returning Failure also counts as failure. Milliseconds use total elapsed time measured by a monotonic clock.

Receive uses finite bucket boundaries of 1, 10, 100, 1000, 5000, 10000, 20000, 30000 and 60000 ms to cover long polling; longer calls fall into the +Inf bucket. These buckets describe latency and do not change request timeouts.

The send/process instrument names and bucket boundaries follow the Apache C# client's metric definitions. Send measures the whole logical operation here, rather than an individual send attempt. Receive latency is an additional instrument. Delivery latency, cache await time, cache gauges, proxy-directed OTLP export and custom propagation are not implemented in this version.

The implementation follows the separation used by RabbitMQ.Client.OpenTelemetry: core .NET diagnostics with a separate provider-registration package. Applications can also subscribe directly with ActivityListener / MeterListener, or register the source and meter names without this package.

EventHorizon.RocketMQ was also consulted for operation scopes, disabled-instrumentation fast paths, and receive/process distinctions. Its receive-parent/producer-link topology, operation/message counters and DI-owned meters are not part of this initial package. Settlement scopes follow its per-attempt model. Receive links use the properties-based producer contexts as in the locally reviewed OpenTelemetry Java RocketMQ 5 instrumentation.