YMJake.RocketMQ.Client.OpenTelemetry 1.1.13

YMJake.RocketMQ.Client.OpenTelemetry

OpenTelemetry instrumentation for YMJake.RocketMQ.Client - Automatic distributed tracing and metrics for Apache RocketMQ 5.x messaging operations.

Features

• ✅ Automatic tracing for message publish and process operations, including LitePushConsumer and LiteSimpleConsumer
• ✅ Optional experimental receive telemetry aligned with OpenTelemetry Java instrumentation
• ✅ Built-in metrics for send/receive/consume latency histograms and broker-controlled OTLP metric export
• ✅ W3C Trace Context propagation (traceparent/tracestate)
• ✅ OpenTelemetry semantic conventions for messaging
• ✅ RocketMQ-specific attributes (message type, tags, etc.)
• ✅ Exception events on failed publish, receive, and process spans when those spans are enabled
• ✅ Batch message support
• ✅ Customizable filtering and captured message headers
• ✅ Zero code changes required in your application

Supports .NET 8.0 (LTS) and .NET 10.0

Installation

dotnet add package YMJake.RocketMQ.Client.OpenTelemetry

Quick Start

using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
using RocketMQ.Client.OpenTelemetry;

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(ResourceBuilder.CreateDefault()
        .AddService("my-service"))
    .AddRocketMqInstrumentation()
    .AddOtlpExporter()  // or AddConsoleExporter(), AddJaegerExporter(), etc.
    .Build();

var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddRocketMqInstrumentation()
    .AddOtlpExporter()
    .Build();

That's it! The tracing instrumentation automatically listens to DiagnosticListener events emitted by the RocketMQ client and produces spans for publish and process operations, while the metrics instrumentation publishes RocketMQ histograms into the OpenTelemetry metrics pipeline and reacts to broker metric settings.

Receive telemetry is experimental in the OpenTelemetry Java instrumentation and is disabled by default here as well. Enable it explicitly if you want separate {topic} receive spans.

If you want a runnable WebAPI example, see RocketMQ.Client.OpenTelemetry.Sample.

Advanced Configuration

Filtering Messages

.AddRocketMqInstrumentation(options =>
{
    // Only trace messages from specific topics
    options.Filter = data => 
        data.Messages.Any(m => m.Topic.StartsWith("important-"));
})

Captured Headers

.AddRocketMqInstrumentation(options =>
{
    options.CapturedHeaders.Add("tenant-id");
    options.CapturedHeaders.Add("order-type");
})

Captured message properties are recorded as messaging.header.{name} attributes.

Experimental Receive Telemetry

.AddRocketMqInstrumentation(options =>
{
    options.EnableReceiveInstrumentation = true;
})

When enabled, successful non-empty receive operations create {topic} receive spans. Process spans become children of receive spans and retain a link to the upstream producer context. Successful empty polls are still skipped, while failed receive attempts create error receive spans.

Metrics

RocketMQ metrics are exposed as histograms under the Apache.RocketMQ.Client meter.

Application Pipeline Registration

var meterProvider = Sdk.CreateMeterProviderBuilder()
    .AddRocketMqInstrumentation()
    .AddOtlpExporter()
    .Build();

Broker-Controlled Exporter

AddRocketMqInstrumentation() on MeterProviderBuilder listens for BrokerMetricSettings diagnostics emitted by the core client. When RocketMQ broker or proxy enables metric export in telemetry Settings, the package automatically creates or resets an OTLP metric exporter using the broker-provided endpoint, timeout, and signed headers.

No extra application code is required beyond registering AddRocketMqInstrumentation() on your MeterProviderBuilder.

The same MeterProvider registration also exposes the RocketMQ histograms through your application metrics pipeline while broker-controlled export remains active when telemetry settings enable it.

Available Histograms

• rocketmq_send_cost_time
• rocketmq_delivery_latency
• rocketmq_await_time
• rocketmq_process_time

Tags by Histogram

• rocketmq_send_cost_time
  • topic
  • client_id
  • invocation_status
• rocketmq_delivery_latency
  • topic
  • client_id
  • consumer_group
• rocketmq_await_time
  • topic
  • client_id
  • consumer_group
• rocketmq_process_time
  • topic
  • client_id
  • consumer_group
  • invocation_status

Span Attributes

The instrumentation follows OpenTelemetry semantic conventions and adds the following attributes:

SemConv Alignment Notes

The package is aligned with RocketMQ's messaging semantic conventions for client-side observability:

• span name: {topic} publish | {topic} process by default; {topic} receive when experimental receive telemetry is enabled
• messaging.system = "rocketmq"
• messaging.operation = "publish" | "receive" | "process"
• messaging.destination.name = topic name
• messaging.rocketmq.client_group = consumer group (receive / process)
• messaging.batch.message_count = batch size (receive)
• messaging.message.id = message ID (publish / process)
• messaging.message.body.size = message body size in bytes (publish / process)
• messaging.rocketmq.message.type = "normal" | "fifo" | "delay" | "transaction" (publish)
• messaging.rocketmq.message.tag = message tag
• messaging.rocketmq.message.group = message group
• messaging.rocketmq.message.keys = message keys
• messaging.rocketmq.message.delivery_timestamp = scheduled delivery timestamp
• messaging.header.{name} = captured message property values (publish / process)

Client-side metrics are intentionally focused on send, delivery, await, and process latency. Broker-side labels such as cluster or broker node identifiers are intentionally not included in this package.

If the core RocketMQ client later exposes stable endpoint and error metadata in diagnostics, the instrumentation can be extended with additional standard attributes such as server.address, server.port, and error.type.

Standard Messaging Attributes

• messaging.system = "rocketmq"
• messaging.operation = "publish" | "receive" | "process"
• messaging.destination.name = topic name
• messaging.message.id = message ID (publish / process)
• messaging.message.body.size = message body size in bytes (publish / process)
• messaging.batch.message_count = number of messages in batch (receive)

RocketMQ-Specific Attributes

• messaging.rocketmq.client_group = consumer group (receive / process)
• messaging.rocketmq.message.type = "normal" | "fifo" | "delay" | "transaction" (publish)
• messaging.rocketmq.message.tag = message tag
• messaging.rocketmq.message.group = message group (for FIFO)
• messaging.rocketmq.message.keys = message keys
• messaging.rocketmq.message.delivery_timestamp = scheduled delivery timestamp (Unix milliseconds)
• messaging.header.{name} = captured message property values (publish / process)

How It Works

The instrumentation uses .NET's DiagnosticListener to subscribe to events emitted by the RocketMQ client. It automatically:

1. Creates spans for publish and process operations by default, and receive operations when experimental receive telemetry is enabled
2. Propagates trace context via message properties (traceparent/tracestate)
3. Makes process spans children of receive spans when receive instrumentation is enabled, while linking them back to producer spans
4. Skips receive spans for successful empty polls, while still creating error receive spans for failed receive attempts when receive telemetry is enabled
5. Sets appropriate span status based on operation results
6. Records OpenTelemetry exception events on failed publish, receive, and process spans when exception details are available from the core client diagnostics

This applies to the client-side consumer variants supported by the core package, including SimpleConsumer, PushConsumer, LitePushConsumer, and LiteSimpleConsumer.

No changes are required in your application code beyond adding the instrumentation to your TracerProvider.

License

Apache License 2.0. Based on Apache RocketMQ Clients.

Links

• Main Package: YMJake.RocketMQ.Client
• Repository: Gitee
• OpenTelemetry Java RocketMQ instrumentation: rocketmq-client-5.0
• OpenTelemetry RocketMQ SemConv: messaging/rocketmq
• OpenTelemetry Messaging Attributes Registry: registry/attributes/messaging