消息队列 / 系统课时
生产者拦截器与指标
生产者拦截器与指标
生产者拦截器适合在消息进入 Kafka 客户端发送链路时补充追踪信息,而客户端指标负责回答“发得慢不慢、批次是否健康、是否发生发送错误”。本课把两者放进同一条观测链路,并给出可直接运行的 Java 示例。
学习目标
- 使用
ProducerInterceptor为消息补充追踪 Header,并理解回调执行边界 - 从
KafkaProducer.metrics()读取请求延迟、批次大小和发送错误指标 - 区分拦截器适合做的轻量观测逻辑与不应放入其中的业务逻辑
拦截器位于发送链路的哪里
调用 KafkaProducer.send() 后,记录会先经过配置的 ProducerInterceptor。onSend() 可以返回修改后的 ProducerRecord,因此很适合补充 trace-id、来源服务或协议版本等元数据;随后客户端完成序列化、分区、批处理和网络发送。
Broker 返回确认或发送失败后,拦截器还会收到 onAcknowledgement()。这条回调不适合执行数据库写入、远程调用或长时间日志处理,因为它会影响客户端 I/O 线程的推进速度。

用拦截器补充追踪 Header
下面示例假设本机已有可访问的 Kafka Broker,地址为 localhost:9092,并且项目已经引入与集群兼容的 kafka-clients。示例发送 100 条消息,再读取三个核心客户端指标。
import org.apache.kafka.clients.producer.*;
import org.apache.kafka.common.Metric;
import org.apache.kafka.common.MetricName;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.Properties;
import java.util.Set;
import java.util.UUID;
public class ProducerObservabilityDemo {
public static final class TraceHeaderInterceptor
implements ProducerInterceptor<String, String> {
@Override
public ProducerRecord<String, String> onSend(ProducerRecord<String, String> record) {
String traceId = UUID.randomUUID().toString();
record.headers().remove("trace-id");
record.headers().add(
"trace-id",
traceId.getBytes(StandardCharsets.UTF_8)
);
return record;
}
@Override
public void onAcknowledgement(RecordMetadata metadata, Exception exception) {
if (exception != null) {
System.err.println("send failed: " + exception.getClass().getSimpleName());
}
}
@Override
public void configure(Map<String, ?> configs) {}
@Override
public void close() {}
}
public static void main(String[] args) {
Properties props = new Properties();
props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG,
"org.apache.kafka.common.serialization.StringSerializer");
props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG,
"org.apache.kafka.common.serialization.StringSerializer");
props.put(ProducerConfig.ACKS_CONFIG, "all");
props.put(ProducerConfig.INTERCEPTOR_CLASSES_CONFIG,
TraceHeaderInterceptor.class.getName());
Set<String> watched = Set.of(
"request-latency-avg",
"batch-size-avg",
"record-error-total"
);
try (KafkaProducer<String, String> producer = new KafkaProducer<>(props)) {
for (int i = 0; i < 100; i++) {
producer.send(new ProducerRecord<>(
"orders.events",
"order-" + i,
"created"
));
}
producer.flush();
for (Map.Entry<MetricName, ? extends Metric> entry
: producer.metrics().entrySet()) {
MetricName name = entry.getKey();
if ("producer-metrics".equals(name.group())
&& watched.contains(name.name())) {
System.out.printf("%s=%s%n",
name.name(),
entry.getValue().metricValue());
}
}
}
}
}预期输出
request-latency-avg=<VALUE>
batch-size-avg=<VALUE>
record-error-total=0.0<VALUE> 会随网络、Broker 负载、消息大小和采样窗口变化;刚启动时个别平均值也可能尚未形成稳定样本。这里更重要的是指标名称和趋势,而不是某次运行的绝对数字。
用指标判断发送是否健康
request-latency-avg 表示客户端请求到收到响应的平均延迟,持续升高通常要继续检查 Broker 负载、网络和请求排队。batch-size-avg 反映实际发送批次的平均字节数;批次长期很小,往往意味着吞吐不足以形成批次,或 linger.ms、batch.size 与流量特征不匹配。
record-error-total 是累计发送错误数。它一旦增长,应结合发送回调中的异常类型一起定位,而不要只看“错误率突然变高”这一条曲线。生产环境通常把 producer.metrics() 接入 JMX、Micrometer 或现有监控系统,而不是像示例那样临时打印。
保持拦截器轻量
拦截器适合做无状态、低成本、失败可容忍的工作,例如补充追踪 Header、记录少量计数或统一标签。不要在 onSend() 中阻塞请求,也不要在 onAcknowledgement() 中执行同步远程调用;真正的重试、告警聚合和持久化审计应交给业务回调或独立观测组件。