Skip to content

Librdkafka Statistics Metrics Details

This page is a copy of the STATISTICS.md of librdkafka.

The statistics presented below are based on the raw metrics from librdkafka. However, Karafka and WaterDrop enhance these metrics for a more comprehensive view. By default, both frameworks have the statistics.interval.ms set to 5 seconds, meaning statistics are refreshed at this interval. Be mindful of this default setting when analyzing metric data.


librdkafka may be configured to emit internal metrics at a fixed interval by setting the statistics.interval.ms configuration property to a value > 0 and registering a stats_cb (or similar, depending on language).

The stats are provided as a JSON object string.

Note: The metrics returned may not be completely consistent between brokers, toppars and totals, due to the internal asynchronous nature of librdkafka. E.g., the top level tx total may be less than the sum of the broker tx values which it represents.

General structure

All fields that contain sizes are in bytes unless otherwise noted.

{
 <Top-level fields>
 "brokers": {
    <brokers fields>,
    "toppars": { <toppars fields> }
 },
 "topics": {
   <topic fields>,
   "partitions": {
     <partitions fields>
   }
 }
[, "cgrp": { <cgrp fields> } ]
[, "eos": { <eos fields> } ]
}

Field type

Fields are represented as follows: * string - UTF8 string. * int - Integer counter (64 bits wide). Ever increasing. * int gauge - Integer gauge (64 bits wide). Will be reset to 0 on each stats emit. * object - Nested JSON object. * bool - true or false.

Top-level

Field Type Example Description
name string "rdkafka#producer-1" Handle instance name
client_id string "rdkafka" The configured (or default) client.id
type string "producer" Instance type (producer or consumer)
ts int 12345678912345 librdkafka's internal monotonic clock (microseconds)
time int Wall clock time in seconds since the epoch
age int Time since this client instance was created (microseconds)
replyq int gauge Number of ops (callbacks, events, etc) waiting in queue for application to serve with rd_kafka_poll()
msg_cnt int gauge Current number of messages in producer queues
msg_size int gauge Current total size of messages in producer queues
msg_max int Threshold: maximum number of messages allowed allowed on the producer queues
msg_size_max int Threshold: maximum total size of messages allowed on the producer queues
tx int Total number of requests sent to Kafka brokers
tx_bytes int Total number of bytes transmitted to Kafka brokers
rx int Total number of responses received from Kafka brokers
rx_bytes int Total number of bytes received from Kafka brokers
txmsgs int Total number of messages transmitted (produced) to Kafka brokers
txmsg_bytes int Total number of message bytes (including framing, such as per-Message framing and MessageSet/batch framing) transmitted to Kafka brokers
rxmsgs int Total number of messages consumed, not including ignored messages (due to offset, etc), from Kafka brokers.
rxmsg_bytes int Total number of message bytes (including framing) received from Kafka brokers
simple_cnt int gauge Internal tracking of legacy vs new consumer API state
metadata_cache_cnt int gauge Number of topics in the metadata cache.
brokers object Dict of brokers, key is broker name, value is object. See brokers below
topics object Dict of topics, key is topic name, value is object. See topics below
cgrp object Consumer group metrics. See cgrp below
eos object EOS / Idempotent producer state and metrics. See eos below

brokers

Per broker statistics.

Field Type Example Description
name string "example.com:9092/13" Broker hostname, port and broker id
nodeid int 13 Broker id (-1 for bootstraps)
nodename string "example.com:9092" Broker hostname
source string "configured" Broker source (learned, configured, internal, logical)
state string "UP" Broker state (INIT, DOWN, CONNECT, AUTH, APIVERSION_QUERY, AUTH_HANDSHAKE, UP, UPDATE)
stateage int gauge Time since last broker state change (microseconds)
outbuf_cnt int gauge Number of requests awaiting transmission to broker
outbuf_msg_cnt int gauge Number of messages awaiting transmission to broker
waitresp_cnt int gauge Number of requests in-flight to broker awaiting response
waitresp_msg_cnt int gauge Number of messages in-flight to broker awaiting response
tx int Total number of requests sent
txbytes int Total number of bytes sent
txerrs int Total number of transmission errors
txretries int Total number of request retries
txidle int Microseconds since last socket send (or -1 if no sends yet for current connection).
req_timeouts int Total number of requests timed out
rx int Total number of responses received
rxbytes int Total number of bytes received
rxerrs int Total number of receive errors
rxcorriderrs int Total number of unmatched correlation ids in response (typically for timed out requests)
rxpartial int Total number of partial MessageSets received. The broker may return partial responses if the full MessageSet could not fit in the remaining Fetch response size.
rxidle int Microseconds since last socket receive (or -1 if no receives yet for current connection).
req object Request type counters. Object key is the request name, value is the number of requests sent.
zbuf_grow int Total number of decompression buffer size increases
buf_grow int Total number of buffer size increases (deprecated, unused)
wakeups int Broker thread poll loop wakeups
connects int Number of connection attempts, including successful and failed, and name resolution failures.
disconnects int Number of disconnects (triggered by broker, network, load-balancer, etc.).
int_latency object Internal producer queue latency in microseconds. See Window stats below
outbuf_latency object Internal request queue latency in microseconds. This is the time between a request is enqueued on the transmit (outbuf) queue and the time the request is written to the TCP socket. Additional buffering and latency may be incurred by the TCP stack and network. See Window stats below
rtt object Broker latency / round-trip time in microseconds. See Window stats below
throttle object Broker throttling time in milliseconds. See Window stats below
toppars object Partitions handled by this broker handle. Key is "topic-partition". See brokers.toppars below

Window stats

Rolling window statistics. The values are in microseconds unless otherwise stated.

Field Type Example Description
min int gauge Smallest value
max int gauge Largest value
avg int gauge Average value
sum int gauge Sum of values
cnt int gauge Number of values sampled
stddev int gauge Standard deviation (based on histogram)
hdrsize int gauge Memory size of Hdr Histogram
p50 int gauge 50th percentile
p75 int gauge 75th percentile
p90 int gauge 90th percentile
p95 int gauge 95th percentile
p99 int gauge 99th percentile
p99_99 int gauge 99.99th percentile
outofrange int gauge Values skipped due to out of histogram range

brokers.toppars

Topic partition assigned to broker.

Field Type Example Description
topic string "mytopic" Topic name
partition int 3 Partition id

topics

Field Type Example Description
topic string "myatopic" Topic name
age int gauge Age of client's topic object (milliseconds)
metadata_age int gauge Age of metadata from broker for this topic (milliseconds)
batchsize object Batch sizes in bytes. See Window stats·
batchcnt object Batch message counts. See Window stats·
partitions object Partitions dict, key is partition id. See partitions below.

partitions

Field Type Example Description
partition int 3 Partition Id (-1 for internal UA/UnAssigned partition)
broker int The id of the broker that messages are currently being fetched from
leader int Current leader broker id
desired bool Partition is explicitly desired by application
unknown bool Partition not seen in topic metadata from broker
msgq_cnt int gauge Number of messages waiting to be produced in first-level queue
msgq_bytes int gauge Number of bytes in msgq_cnt
xmit_msgq_cnt int gauge Number of messages ready to be produced in transmit queue
xmit_msgq_bytes int gauge Number of bytes in xmit_msgq
fetchq_cnt int gauge Number of pre-fetched messages in fetch queue
fetchq_size int gauge Bytes in fetchq
fetch_state string "active" Consumer fetch state for this partition (none, stopping, stopped, offset-query, offset-wait, active).
query_offset int gauge Current/Last logical offset query
next_offset int gauge Next offset to fetch
app_offset int gauge Offset of last message passed to application + 1
stored_offset int gauge Offset to be committed
stored_leader_epoch int Partition leader epoch of stored offset
committed_offset int gauge Last committed offset
committed_leader_epoch int Partition leader epoch of committed offset
eof_offset int gauge Last PARTITION_EOF signaled offset
lo_offset int gauge Partition's low watermark offset on broker
hi_offset int gauge Partition's high watermark offset on broker
ls_offset int gauge Partition's last stable offset on broker, or same as hi_offset is broker version is less than 0.11.0.0.
consumer_lag int gauge Difference between (hi_offset or ls_offset) and committed_offset). hi_offset is used when isolation.level=read_uncommitted, otherwise ls_offset.
consumer_lag_stored int gauge Difference between (hi_offset or ls_offset) and stored_offset. See consumer_lag and stored_offset.
leader_epoch int Last known partition leader epoch, or -1 if unknown.
txmsgs int Total number of messages transmitted (produced)
txbytes int Total number of bytes transmitted for txmsgs
rxmsgs int Total number of messages consumed, not including ignored messages (due to offset, etc).
rxbytes int Total number of bytes received for rxmsgs
msgs int Total number of messages received (consumer, same as rxmsgs), or total number of messages produced (possibly not yet transmitted) (producer).
rx_ver_drops int Dropped outdated messages
msgs_inflight int gauge Current number of messages in-flight to/from broker
next_ack_seq int gauge Next expected acked sequence (idempotent producer)
next_err_seq int gauge Next expected errored sequence (idempotent producer)
acked_msgid int Last acked internal message id (idempotent producer)

cgrp

Field Type Example Description
state string "up" Local consumer group handler's state.
stateage int gauge Time elapsed since last state change (milliseconds).
join_state string "assigned" Local consumer group handler's join state.
rebalance_age int gauge Time elapsed since last rebalance (assign or revoke) (milliseconds).
rebalance_cnt int Total number of rebalances (assign or revoke).
rebalance_reason string Last rebalance reason, or empty string.
assignment_size int gauge Current assignment's partition count.

eos

Field Type Example Description
idemp_state string "Assigned" Current idempotent producer id state.
idemp_stateage int gauge Time elapsed since last idemp_state change (milliseconds).
txn_state string "InTransaction" Current transactional producer state.
txn_stateage int gauge Time elapsed since last txn_state change (milliseconds).
txn_may_enq bool Transactional state allows enqueuing (producing) new messages.
producer_id int gauge The currently assigned Producer ID (or -1).
producer_epoch int gauge The current epoch (or -1).
epoch_cnt int The number of Producer ID assignments since start.

Example output

This (prettified) example output is from a short-lived producer using the following command: rdkafka_performance -b localhost -P -t test -T 1000 -Y 'cat >> stats.json'.

Note: this output is prettified using jq ., the JSON object emitted by librdkafka does not contain line breaks.

{
  "name": "rdkafka#producer-1",
  "client_id": "rdkafka",
  "type": "producer",
  "ts": 5016483227792,
  "time": 1527060869,
  "replyq": 0,
  "msg_cnt": 22710,
  "msg_size": 704010,
  "msg_max": 500000,
  "msg_size_max": 1073741824,
  "simple_cnt": 0,
  "metadata_cache_cnt": 1,
  "brokers": {
    "localhost:9092/2": {
      "name": "localhost:9092/2",
      "nodeid": 2,
      "nodename": "localhost:9092",
      "source": "learned",
      "state": "UP",
      "stateage": 9057234,
      "outbuf_cnt": 0,
      "outbuf_msg_cnt": 0,
      "waitresp_cnt": 0,
      "waitresp_msg_cnt": 0,
      "tx": 320,
      "txbytes": 84283332,
      "txerrs": 0,
      "txretries": 0,
      "req_timeouts": 0,
      "rx": 320,
      "rxbytes": 15708,
      "rxerrs": 0,
      "rxcorriderrs": 0,
      "rxpartial": 0,
      "zbuf_grow": 0,
      "buf_grow": 0,
      "wakeups": 591067,
      "int_latency": {
        "min": 86,
        "max": 59375,
        "avg": 23726,
        "sum": 5694616664,
        "stddev": 13982,
        "p50": 28031,
        "p75": 36095,
        "p90": 39679,
        "p95": 43263,
        "p99": 48639,
        "p99_99": 59391,
        "outofrange": 0,
        "hdrsize": 11376,
        "cnt": 240012
      },
      "rtt": {
        "min": 1580,
        "max": 3389,
        "avg": 2349,
        "sum": 79868,
        "stddev": 474,
        "p50": 2319,
        "p75": 2543,
        "p90": 3183,
        "p95": 3199,
        "p99": 3391,
        "p99_99": 3391,
        "outofrange": 0,
        "hdrsize": 13424,
        "cnt": 34
      },
      "throttle": {
        "min": 0,
        "max": 0,
        "avg": 0,
        "sum": 0,
        "stddev": 0,
        "p50": 0,
        "p75": 0,
        "p90": 0,
        "p95": 0,
        "p99": 0,
        "p99_99": 0,
        "outofrange": 0,
        "hdrsize": 17520,
        "cnt": 34
      },
      "toppars": {
        "test-1": {
          "topic": "test",
          "partition": 1
        }
      }
    },
    "localhost:9093/3": {
      "name": "localhost:9093/3",
      "nodeid": 3,
      "nodename": "localhost:9093",
      "source": "learned",
      "state": "UP",
      "stateage": 9057209,
      "outbuf_cnt": 0,
      "outbuf_msg_cnt": 0,
      "waitresp_cnt": 0,
      "waitresp_msg_cnt": 0,
      "tx": 310,
      "txbytes": 84301122,
      "txerrs": 0,
      "txretries": 0,
      "req_timeouts": 0,
      "rx": 310,
      "rxbytes": 15104,
      "rxerrs": 0,
      "rxcorriderrs": 0,
      "rxpartial": 0,
      "zbuf_grow": 0,
      "buf_grow": 0,
      "wakeups": 607956,
      "int_latency": {
        "min": 82,
        "max": 58069,
        "avg": 23404,
        "sum": 5617432101,
        "stddev": 14021,
        "p50": 27391,
        "p75": 35839,
        "p90": 39679,
        "p95": 42751,
        "p99": 48639,
        "p99_99": 58111,
        "outofrange": 0,
        "hdrsize": 11376,
        "cnt": 240016
      },
      "rtt": {
        "min": 1704,
        "max": 3572,
        "avg": 2493,
        "sum": 87289,
        "stddev": 559,
        "p50": 2447,
        "p75": 2895,
        "p90": 3375,
        "p95": 3407,
        "p99": 3583,
        "p99_99": 3583,
        "outofrange": 0,
        "hdrsize": 13424,
        "cnt": 35
      },
      "throttle": {
        "min": 0,
        "max": 0,
        "avg": 0,
        "sum": 0,
        "stddev": 0,
        "p50": 0,
        "p75": 0,
        "p90": 0,
        "p95": 0,
        "p99": 0,
        "p99_99": 0,
        "outofrange": 0,
        "hdrsize": 17520,
        "cnt": 35
      },
      "toppars": {
        "test-0": {
          "topic": "test",
          "partition": 0
        }
      }
    },
    "localhost:9094/4": {
      "name": "localhost:9094/4",
      "nodeid": 4,
      "nodename": "localhost:9094",
      "source": "learned",
      "state": "UP",
      "stateage": 9057207,
      "outbuf_cnt": 0,
      "outbuf_msg_cnt": 0,
      "waitresp_cnt": 0,
      "waitresp_msg_cnt": 0,
      "tx": 1,
      "txbytes": 25,
      "txerrs": 0,
      "txretries": 0,
      "req_timeouts": 0,
      "rx": 1,
      "rxbytes": 272,
      "rxerrs": 0,
      "rxcorriderrs": 0,
      "rxpartial": 0,
      "zbuf_grow": 0,
      "buf_grow": 0,
      "wakeups": 4,
      "int_latency": {
        "min": 0,
        "max": 0,
        "avg": 0,
        "sum": 0,
        "stddev": 0,
        "p50": 0,
        "p75": 0,
        "p90": 0,
        "p95": 0,
        "p99": 0,
        "p99_99": 0,
        "outofrange": 0,
        "hdrsize": 11376,
        "cnt": 0
      },
      "rtt": {
        "min": 0,
        "max": 0,
        "avg": 0,
        "sum": 0,
        "stddev": 0,
        "p50": 0,
        "p75": 0,
        "p90": 0,
        "p95": 0,
        "p99": 0,
        "p99_99": 0,
        "outofrange": 0,
        "hdrsize": 13424,
        "cnt": 0
      },
      "throttle": {
        "min": 0,
        "max": 0,
        "avg": 0,
        "sum": 0,
        "stddev": 0,
        "p50": 0,
        "p75": 0,
        "p90": 0,
        "p95": 0,
        "p99": 0,
        "p99_99": 0,
        "outofrange": 0,
        "hdrsize": 17520,
        "cnt": 0
      },
      "toppars": {}
    }
  },
  "topics": {
    "test": {
      "topic": "test",
      "metadata_age": 9060,
      "batchsize": {
        "min": 99,
        "max": 391805,
        "avg": 272593,
        "sum": 18808985,
        "stddev": 180408,
        "p50": 393215,
        "p75": 393215,
        "p90": 393215,
        "p95": 393215,
        "p99": 393215,
        "p99_99": 393215,
        "outofrange": 0,
        "hdrsize": 14448,
        "cnt": 69
      },
      "batchcnt": {
        "min": 1,
        "max": 10000,
        "avg": 6956,
        "sum": 480028,
        "stddev": 4608,
        "p50": 10047,
        "p75": 10047,
        "p90": 10047,
        "p95": 10047,
        "p99": 10047,
        "p99_99": 10047,
        "outofrange": 0,
        "hdrsize": 8304,
        "cnt": 69
      },
      "partitions": {
        "0": {
          "partition": 0,
          "broker": 3,
          "leader": 3,
          "desired": false,
          "unknown": false,
          "msgq_cnt": 1,
          "msgq_bytes": 31,
          "xmit_msgq_cnt": 0,
          "xmit_msgq_bytes": 0,
          "fetchq_cnt": 0,
          "fetchq_size": 0,
          "fetch_state": "none",
          "query_offset": 0,
          "next_offset": 0,
          "app_offset": -1001,
          "stored_offset": -1001,
          "commited_offset": -1001,
          "committed_offset": -1001,
          "eof_offset": -1001,
          "lo_offset": -1001,
          "hi_offset": -1001,
          "consumer_lag": -1,
          "txmsgs": 2150617,
          "txbytes": 66669127,
          "rxmsgs": 0,
          "rxbytes": 0,
          "msgs": 2160510,
          "rx_ver_drops": 0
        },
        "1": {
          "partition": 1,
          "broker": 2,
          "leader": 2,
          "desired": false,
          "unknown": false,
          "msgq_cnt": 0,
          "msgq_bytes": 0,
          "xmit_msgq_cnt": 0,
          "xmit_msgq_bytes": 0,
          "fetchq_cnt": 0,
          "fetchq_size": 0,
          "fetch_state": "none",
          "query_offset": 0,
          "next_offset": 0,
          "app_offset": -1001,
          "stored_offset": -1001,
          "commited_offset": -1001,
          "committed_offset": -1001,
          "eof_offset": -1001,
          "lo_offset": -1001,
          "hi_offset": -1001,
          "consumer_lag": -1,
          "txmsgs": 2150136,
          "txbytes": 66654216,
          "rxmsgs": 0,
          "rxbytes": 0,
          "msgs": 2159735,
          "rx_ver_drops": 0
        },
        "-1": {
          "partition": -1,
          "broker": -1,
          "leader": -1,
          "desired": false,
          "unknown": false,
          "msgq_cnt": 0,
          "msgq_bytes": 0,
          "xmit_msgq_cnt": 0,
          "xmit_msgq_bytes": 0,
          "fetchq_cnt": 0,
          "fetchq_size": 0,
          "fetch_state": "none",
          "query_offset": 0,
          "next_offset": 0,
          "app_offset": -1001,
          "stored_offset": -1001,
          "commited_offset": -1001,
          "committed_offset": -1001,
          "eof_offset": -1001,
          "lo_offset": -1001,
          "hi_offset": -1001,
          "consumer_lag": -1,
          "txmsgs": 0,
          "txbytes": 0,
          "rxmsgs": 0,
          "rxbytes": 0,
          "msgs": 1177,
          "rx_ver_drops": 0
        }
      }
    }
  },
  "tx": 631,
  "tx_bytes": 168584479,
  "rx": 631,
  "rx_bytes": 31084,
  "txmsgs": 4300753,
  "txmsg_bytes": 133323343,
  "rxmsgs": 0,
  "rxmsg_bytes": 0
}