Kratos 默认不支持 ClickHouse 日志写入,因log.Writer仅提供Write([]byte)方法,而ClickHouse需结构化批量插入、表结构对齐及类型匹配,直接使用会导致解析失败或性能崩溃。

Kratos 默认不支持 ClickHouse 日志写入,必须自定义日志 Writer 并绕过 log.Helper 的默认 JSON 格式约束,否则会因字段类型不匹配或插入失败直接丢日志。
为什么不能直接用 kratos/log 的 Writer 接 ClickHouse
Kratos 的 log.Writer 接口只暴露 Write([]byte) 方法,但 ClickHouse 要求结构化数据(如 INSERT INTO ... VALUES (...)),且需预建表、类型对齐、批量提交。原生日志输出是纯文本行或 JSON 字符串,没有 schema 意识;若强行把 log.Info("msg", "user_id", 123) 的输出塞进 ClickHouse,大概率触发 Cannot parse input: expected '(' 或 There is no supertype for types String and UInt64 类错误。
常见踩坑点:
- 直接把
log.NewHelper(log.With(...))的输出管道到clickhouse-go的Conn.Exec—— 每条日志都是一次 SQL,性能崩盘,QPS 不到 50 - 用
log.SetWriter(os.Stdout)+ 外部 logstash / vector 做解析 —— 增加部署复杂度,丢失 trace_id / span_id 上下文字段 - 忽略 ClickHouse 表引擎选型,建了
ReplacingMergeTree却没设version字段,导致重复日志无法去重
推荐方案:封装 clickhouse-go 的 Batch 写入器实现 log.Writer
核心思路是:让 Kratos 日志调用仍走标准 log.Helper 流程,但底层 Writer 把每条日志解析为结构体,攒批后用 conn.PrepareBatch() 插入。
实操要点:
- 定义日志结构体,字段名与 ClickHouse 表列名严格一致,类型映射合理(如
time.Time→DateTime64(3),string→String,int64→Int64) - 在
Writer.Write()中用json.Unmarshal解析 Kratos 输出的 JSON 行(注意:Kratos 默认每行一个 JSON 对象,不是数组) - 用
sync.Pool缓存*clickhouse.Batch实例,避免高频分配 - 设置超时和最大 batch size(建议 1000 条或 1MB),超时未满也强制 flush,防止日志堆积
- 务必在
Close()方法中调用batch.Send(),否则进程退出时日志丢失
示例关键代码片段:
type CHLogWriter struct {
conn clickhouse.Conn
table string
pool *sync.Pool
mu sync.Mutex
}
func (w *CHLogWriter) Write(p []byte) (n int, err error) {
var entry map[string]interface{}
if err = json.Unmarshal(p, &entry); err != nil {
return len(p), err
}
w.mu.Lock()
batch := w.pool.Get().(*clickhouse.Batch)
batch.Append(
entry["time"].(string),
entry["level"].(string),
entry["msg"].(string),
int64(entry["trace_id"].(float64)), // 注意 float64 → int64 转换
)
w.mu.Unlock()
if batch.Rows() >= 1000 {
batch.Send()
w.pool.Put(batch)
}
return len(p), nil
}
ClickHouse 表设计与 Kratos 日志字段对齐
表结构必须提前建好,且字段顺序、类型、默认值要和 Writer 中 batch.Append(...) 的参数顺序完全一致,否则 batch.Append 会静默失败或报错 Code: 48, e.displayText() = DB::Exception: Number of columns doesn't match。
推荐建表语句(含必要索引和 TTL):
CREATE TABLE IF NOT EXISTS logs ( time DateTime64(3) CODEC(Delta, LZ4), level String CODEC(LZ4), msg String CODEC(LZ4), trace_id UInt64 CODEC(DoubleDelta, LZ4), span_id UInt64 CODEC(DoubleDelta, LZ4), service String CODEC(LZ4), host String CODEC(LZ4) ) ENGINE = MergeTree() PARTITION BY toYYYYMMDD(time) ORDER BY (toStartOfHour(time), level, trace_id) TTL time + INTERVAL 30 DAY SETTINGS index_granularity = 8192;
注意:
-
trace_id和span_id在 Kratos 中默认是字符串(如"12345678901234567890"),但 ClickHouse 更适合存为UInt64(需截断或哈希),否则无法高效 join 或 group - 不要用
JSON类型存整个日志对象 —— ClickHouse 的 JSON 函数性能差,且无法走主键索引 - 如果需要保留原始 JSON 字段做兜底,加一列
raw String CODEC(LZ4),写入前json.Marshal原始entry
生产环境必须打开的两个开关
不配这两项,日志写入延迟高、丢数据风险大:
-
clickhouse-go连接串加?compress=true&read_timeout=30&write_timeout=30,否则网络抖动时 batch.Send() 阻塞主线程 - ClickHouse 服务端配置
max_insert_block_size = 1048576和min_insert_block_size_rows = 1000,匹配你的 batch 策略
最易被忽略的一点:Kratos 启动时调用 log.Init() 之前,必须确保 CHLogWriter 的 conn 已成功 Dial,否则日志初始化失败会导致整个服务 panic —— 因为 Kratos 的 log.Init() 是同步阻塞的,不会重试。











