RocketMQ (Prometheus)¶

Apache RocketMQ is a distributed messaging and stream processing platform for decoupling services, smoothing traffic peaks, and event-driven applications.

This integration uses the DataKit Prom collector to scrape the built-in Prometheus metrics of the Broker and the OpenTelemetry collector to receive Producer and PushConsumer client metrics from the new Java SDK, then reports them to the platform.

Broker /metrics → DataKit prom → rocketmq measurement
Java Producer / PushConsumer → OTLP/gRPC → DataKit opentelemetry → otel_service measurement

See the official RocketMQ metrics documentation for supported versions. For environments using a standalone Exporter, see RocketMQ Integration.

Configuration¶

Prerequisites¶

• A running RocketMQ Broker, version 5.1.0 or later.
• Access to edit the configuration file actually loaded by the Broker and restart the service. In a cluster, enable the metrics endpoint on every Broker you plan to monitor.
• DataKit can access the metrics port of each Broker. This guide uses the default port 5557.
• A Topic, consumer group, and production/consumption traffic for verification. Without application traffic, some metrics may be zero or have no corresponding series.

To collect producer and consumer client metrics, the following requirements also apply:

• NameServer, Broker, and Proxy are running, and Proxy can access NameServer and Broker.
• The application uses Producer and PushConsumer from the new Java SDK rocketmq-client-java:5.2.2. This guide uses JDK 17.
• You can modify the JSON configuration actually loaded by Proxy and restart Proxy.
• Clients can access the Proxy gRPC port (default 8081) and directly access the DataKit OTLP/gRPC receiver port (4317 in this guide).

Enable the built-in Prometheus metrics on the Broker¶

Edit the configuration file actually specified by the Broker startup argument -c, usually broker.conf, and add:

metricsExporterType=PROM
metricsPromExporterHost=0.0.0.0
metricsPromExporterPort=5557

After saving, restart the corresponding Broker using your existing deployment procedure; perform rolling restarts in production clusters according to your maintenance process. Then verify the metrics endpoint on the Broker host:

curl -fsS http://127.0.0.1:5557/metrics

The response should contain metrics prefixed with rocketmq_ and their type information. Also verify endpoint accessibility from the DataKit host using the actual Broker address.

metricsPromExporterHost=0.0.0.0 listens on all network interfaces. Restrict access with security groups or a firewall. For Docker deployments, map the container port 5557 to a host port accessible to DataKit. If DataKit also runs in a container, its 127.0.0.1 refers to the DataKit container itself.

Configure the Prom collector¶

Copy the sample Prom collector configuration on the DataKit host:

mkdir -p /usr/local/datakit/conf.d/prom
cp /usr/local/datakit/conf.d/samples/prom.conf.sample \
  /usr/local/datakit/conf.d/prom/rocketmq.conf

Edit rocketmq.conf and replace its contents with:

[[inputs.prom]]
  urls = ["http://127.0.0.1:5557/metrics"]
  ignore_req_err = false
  source = "rocketmq"
  # An empty list collects all metric types, including Counter, Gauge, and Histogram
  metric_types = []
  metric_name_filter = ["^rocketmq_"]
  interval = "10s"
  measurement_prefix = ""
  measurement_name = "rocketmq"
  # Preserve the full Prometheus metric field names
  keep_exist_metric_name = true

See the Prom collector documentation for more parameters.

For cluster deployments, replace urls in the configuration with the actual metrics addresses of the Brokers:

urls = [
  "http://<BROKER_1_IP>:5557/metrics",
  "http://<BROKER_2_IP>:5557/metrics"
]

Alternatively, deploy DataKit on each Broker host and collect the local endpoint. Choose one coverage method to avoid collecting the same endpoint twice.

After saving the configuration, restart DataKit to apply it:

datakit service restart

Collect producer and consumer client metrics¶

The Broker /metrics endpoint provides server metrics. The new Java SDK reports producer send latency, PushConsumer consumption callback latency, local queueing, and cache metrics directly to DataKit through OTLP/gRPC. Enable the following client collection pipeline.

Enable the DataKit OTLP receiver¶

When enabling the OpenTelemetry collector for the first time, copy the sample configuration:

mkdir -p /usr/local/datakit/conf.d/opentelemetry
cp /usr/local/datakit/conf.d/samples/opentelemetry.conf.sample \
  /usr/local/datakit/conf.d/opentelemetry/opentelemetry.conf

If the collector is already enabled, modify its existing configuration to avoid creating duplicate receiver instances. Set the listening address in the gRPC configuration for [[inputs.opentelemetry]] and retain the other settings in the file:

[inputs.opentelemetry.grpc]
  addr = "127.0.0.1:4317"

Save the configuration, restart DataKit, and check the listening port:

datakit service restart
ss -lnt | grep ':4317'

127.0.0.1:4317 only applies when the client and DataKit run on the same host or share a network namespace. For deployments across hosts, change the listening address to the private IP of DataKit or 0.0.0.0:4317, and restrict access with security groups or a firewall. Client TLS settings must match the receiver configuration; the example above uses plaintext gRPC.

For more configuration details, see the DataKit OpenTelemetry collector.

Enable client metrics through Proxy¶

Merge the following fields into the JSON configuration actually loaded when Proxy starts, retaining existing application settings:

{
  "metricCollectorMode": "ON",
  "metricCollectorAddress": "127.0.0.1:4317"
}

metricCollectorMode is disabled by default. When set to ON, clients report metrics directly to DataKit using the address supplied by Proxy. Set metricCollectorAddress to a DataKit address reachable from clients, in host:port format, such as <DATAKIT_IP>:4317.

Here, 127.0.0.1 is resolved on the client host or container and can only be used when the client and DataKit run on the same host or share a network namespace. For deployments across hosts or containers, adjust both the DataKit listening address and the address supplied by Proxy.

Save the configuration and restart the corresponding Proxy using your existing deployment procedure. For Proxy configuration fields, see RocketMQ 5.3.3 ProxyConfig.

Connect application clients¶

In the new Java SDK client configuration, set endpoints to a Proxy address reachable from clients, such as <PROXY_HOST>:8081. Once the application Producer and PushConsumer send and receive messages normally, the SDK automatically reports client metrics to DataKit according to the metrics configuration supplied by Proxy.

endpoints points to the Proxy used for application access, while metricCollectorAddress points to the DataKit metrics receiver. These addresses serve different purposes. For the client metrics export implementation in the new Java SDK, see ClientMeterManager.

Verify collection results¶

Broker metrics¶

Use the Prom configuration debug command to inspect the converted measurement, fields, and tags:

datakit debug --prom-conf /usr/local/datakit/conf.d/prom/rocketmq.conf

The debug output should include the rocketmq measurement and fields prefixed with rocketmq_. Use the following command to check collector status and request errors:

datakit monitor

Client metrics¶

The SDK reports client metrics periodically. This reporting interval is independent of the Prom interval="10s"; the measurement name is otel_service.

Metrics¶

Broker metrics¶

Broker metrics are written to the rocketmq measurement, retaining full Prometheus field names. The fields actually available depend on Broker /metrics, DataKit debug output, and ingested data.

The official RocketMQ logical metrics rocketmq_consumer_lag_latency and rocketmq_rpc_latency have the unit suffix _milliseconds in this example. Histogram metrics expand into _bucket, _sum, and _count, such as rocketmq_rpc_latency_milliseconds_bucket. Check the actual fields and units before creating views and monitors.

Counters are cumulative values and cannot directly represent TPS or per-second throughput. After calculating the per-second rate, message counts use messages/s and byte counts use Byte/s. Gauges represent the current state; observe the values and trends of ready messages, inflight messages, and consumer lag directly. Consumer lag is the waiting time of the earliest unacknowledged message, rather than the average processing time of completed messages.

Producer and consumer client metrics¶

The following metrics are generated by the new Java SDK and written to the otel_service measurement through the OTLP/gRPC pipeline described here.

In this pipeline, client Histograms expand into _bucket, _sum, and _count fields without the _milliseconds suffix. For example, producer send latency corresponds to rocketmq_send_cost_time_bucket, rocketmq_send_cost_time_sum, and rocketmq_send_cost_time_count.

Latency values and le bucket boundaries are in milliseconds. _sum is cumulative latency, while _bucket and _count are cumulative sample counts. P95 / P99 are estimated from histogram buckets. Calculating the per-second rate of _count yields the latency sample rate, which is not message TPS. The two Gauges use the original field names in the table.

Common tags¶

Tags vary by metric; use the actual collected data as the reference. Broker storage metrics are usually viewed by cluster and node_id, and Broker consumer group metrics by cluster, topic, and consumer_group. Filter client metrics using the tags actually present, such as client_id, topic, and consumer_group; do not assume they have the Broker tags cluster and node_id.

Display client metrics¶

Select the otel_service measurement for client latency and cache charts, and continue using rocketmq for Broker charts. Before reusing a dashboard, verify the actual measurements, fields, units, and tags, and adjust chart and variable queries as needed. The Cluster filter applies only to Broker metrics; the client_id filter applies only to client metrics.

Viewing the last 30 minutes is recommended. If client latency and sample rate charts use a 5-minute aggregation interval, the last 5 minutes may contain only one point. Choose the time range based on the actual sample count.

FAQ¶

Broker data is available, but producer or consumer client metrics are missing¶

Client metrics are reported separately through OTLP/gRPC and are not enabled by the Broker Prom collection configuration. Check, in order, the DataKit listener on 4317, the metricCollectorMode and metricCollectorAddress actually loaded by Proxy, service restarts after configuration changes, and client-to-DataKit network connectivity.

Confirm that the application uses Producer and PushConsumer from the new Java SDK described here and has generated application traffic, with endpoints pointing to a reachable Proxy. Across hosts or containers, the client-local 127.0.0.1 cannot be used as a remote DataKit address. Wait for the SDK to complete its periodic report, then check data in otel_service.

Client latency fields do not have the _milliseconds suffix¶

Field conversion differs between the Broker Prometheus pipeline and the client OTLP pipeline. Clients use fields such as rocketmq_send_cost_time_bucket, rocketmq_process_time_bucket, and rocketmq_await_time_bucket. Values and bucket boundaries are still in milliseconds; do not directly apply the field suffix of Broker latency metrics.