因日志采集对吞吐和稳定性要求高，sarama经多年压测验证，在批量发送、重试退避、连接复用上更稳健；franz-go默认异步写入和自动元数据刷新易导致UnknownTopicOrPartition错误。
为什么用 sarama 而不是 franz-go 做日志采集客户端
日志采集对吞吐和稳定性要求高，sarama 是 Go 生态最成熟的 Kafka 客户端，但默认配置下容易在高并发写入时触发 OutOfMemory 或连接抖动。它支持同步/异步生产者、自定义分区器、重试策略，且与 logrus / zerolog 日志库能自然衔接；franz-go 虽更轻量、API 更现代，但其 RecordBatch 内存复用机制在日志高频打点场景下需手动管理缓冲区，反而增加出错概率。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 选用
sarama.AsyncProducer，禁用sarama.SyncProducer（阻塞式会拖垮 HTTP handler） - 设置
Config.Producer.Return.Successes = true，否则无法感知发送结果 - 必须显式调用
Close()释放 goroutine 和连接，否则进程退出时残留连接会卡住 Kafka broker - 避免在
Successeschannel 上无缓冲读取——日志峰值时 channel 可能堆积，改用带超时的select非阻塞消费
如何让日志结构体自动序列化为 Kafka 消息并保留时间戳
Kafka 消息本身不携带语义化时间戳（timestamp 字段是 broker 接收时间），而日志分析依赖客户端打点时刻。不能依赖 time.Now() 在发送前塞字段，因为 AsyncProducer 的缓冲和重试会导致实际发送时间漂移。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在日志结构体中预埋
Timestamp int64字段，由日志中间件在Write()入口统一赋值：time.Now().UnixMilli() - 用
json.Marshal()序列化结构体，不要用fmt.Sprintf拼接字符串——后者无法保证字段顺序，且易引入空格或换行破坏 JSON 格式 - 若需压缩（如日志体积 >1MB），启用
Config.Producer.Compression = sarama.CompressionSnappy，但注意 Kafka broker 端需加载对应解压库 - 禁止将
*log.Entry直接传给 producer——它含未导出字段，json包会忽略，导致关键字段丢失
框架集成时怎么避免 HTTP handler 阻塞在 Kafka 发送路径上
常见错误是把 producer.Input() 放在 handler 主流程里，一旦 Kafka 集群短暂不可用，<code>Input() channel 会阻塞（默认无缓冲），整个 HTTP 请求 hang 死。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 声明带缓冲的
Input()channel：producer.Input() = make(chan *sarama.ProducerMessage, 1024)，容量按 QPS × 平均延迟 × 2 估算 - 启动独立 goroutine 消费
Successes和Errorschannel，记录失败消息到本地磁盘（如/var/log/app/kafka-failures.log），供后续重投 - 在 handler 中只做非阻塞写入：
select { case producer.Input() - 不要在 handler 里调用
producer.Close()——它会等待所有消息发送完成，应放在http.Server.Shutdown()回调中
部署后发现日志重复或乱序，该怎么定位
重复通常源于重试 + 幂等性关闭；乱序多因分区策略不当或异步发送未保序。Kafka 仅保证单 partition 内消息有序，而日志采集常跨多个 topic（如 app-log、error-log）。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 开启幂等性：
Config.Producer.Idempotent = true，并确保Config.Producer.RequiredAcks = sarama.WaitForAll，否则幂等无效 - 避免用
sarama.NewHashPartitioner对日志内容哈希——不同服务日志结构差异大，哈希结果不可控；改用sarama.NewRoundRobinPartitioner或固定分区（如0）测试保序性 - 检查 broker 端
log.message.timestamp.type=CreateTime，确认未被覆盖为LogAppendTime - 在消费者端加简单校验：解析消息体中的
Timestamp字段，若连续 5 条时间倒流 >1s，触发告警而非丢弃
真正麻烦的是跨服务日志因果关系丢失——比如 A 服务调用 B 服务，B 的日志时间戳早于 A。这没法靠 Kafka 解决，得在框架层注入 trace_id 和 parent_span_id，再通过日志字段透传。
