...

This page is meant as a template for writing a KIP. To create a KIP choose Tools->Copy on this page and modify with your content and replace the heading with the next KIP number and a description of your issue. Replace anything in italics with your own description.

Status

Current state: Under DiscussionAccepted

Discussion thread: here

Vote Thread: here

JIRA: here

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

...

Metric Semantics and Behaviour

Metric Cardinality:

• Question: How many metric instances will this create per broker?
  • The proposed I/O metrics have low cardinality - specifically 7 metrics per broker process.
  • These metrics are process-level counters, not topic-level (like `BytesInPerSec` (per topic), partition-level ( `LogEndOffset`), or replica-level metrics(`UnderReplicatedPartitions`).
  • Cardinality Breakdown - Per Broker Process:
    • `linux-disk-read-bytes`: 1 metric (existing)
    • `linux-disk-write-bytes`: 1 metric (existing)
    • `linux-disk-rchar`: 1 metric (new)
    • `linux-disk-wchar`: 1 metric (new)
    • `linux-disk-syscr`: 1 metric (new)
    • `linux-disk-syscw`: 1 metric (new)
    • `linux-disk-cancelled-write-bytes`: 1 metric (new)

...

Public Interfaces

JMX Metrics

All metrics exposed under kafka.server:type=KafkaServer,name=<metric-name> :

For Example: (Existing metric)

Scope Note: The `linux-disk-*` prefix is a historical naming convention inherited 
from the two existing metrics. All seven metrics in this group reflect aggregate I/O
for the Kafka JVM process across all configured `log.dirs`. They do not provide
per-disk or per-log-directory visibility.

All metrics are exposed under:
- Brokers: kafka.server:type=KafkaServer,name=<metric-name>
- Controllers: kafka.server:type=ControllerServer,name=<metric-name>

          In combined mode (broker + controller on the same node), both sets of metrics are registered, but they share the same underlying LinuxIoMetricsCollector reading from the same /proc/self/io, so the values reflect aggregate process-level I/O.

For Example: (Existing metric)

Broker:     kafka.server type=KafkaServer name=linux-disk-read-kafka.server type=KafkaServer name=linux-disk-read-bytes  Value=16384 JMXTool=1.5.3 
Controller: kafka.server type=ControllerServer name=linux-disk-read-bytes  Value=16384 JMXTool=1.5.3

New Metrics:

Metric Name: linux-disk-rchar
Type: Gauge
Unit: Bytes
Description: Total bytes read (including page cache hits)
Use Case: Calculate cache hit ratio: (rchar - read_bytes) / rchar
────────────────────────────────────────
Metric Name: linux-disk-wchar
Type: Gauge
Unit: Bytes
Description: Total bytes written (including buffered writes)
Use Case: Detect write amplification: write_bytes / wchar
────────────────────────────────────────
Metric Name: linux-disk-syscr
Type: Gauge
Unit: Count
Description: Number of read system calls
Use Case: Identify inefficient I/O patterns: read_bytes / syscr for avg read size
────────────────────────────────────────
Metric Name: linux-disk-syscw
Type: Gauge
Unit: Count
Description: Number of write system calls
Use Case: Analyze write batching: write_bytes / syscw for avg write size
────────────────────────────────────────
Metric Name: linux-disk-cancelled-write-bytes
Type: Gauge
Unit: Bytes
Description: Bytes cancelled before write (truncations)
Use Case: Monitor log compaction and cleanup activity
────────────────────────────────────────
Metric Name: linux-disk-read-bytes (existing)
Type: Gauge
Unit: Bytes
Description: Bytes read from storage layer (actual disk I/O)
Use Case: Track physical disk reads
────────────────────────────────────────
Metric Name: linux-disk-write-bytes (existing)
Type: Gauge
Unit: Bytes
Description: Bytes written to storage layer (actual disk I/O)
Use Case: Track physical disk writes

...