grpc/custom_logger
gRPC 服务端访问日志拦截器:仿 Gin debug 模式的一行 access log(Unary + Stream)。
概述
针对 Unary / Stream RPC 输出形如:
[GRPC] 2026-01-01T12:00:00.000+0800 | 0 | 1.23ms | 127.0.0.1:54321 | [request_id:V1StGXR8_Z5jdHi6B] /pkg.Service/Method OK
字段含义依次为:开始时间戳、gRPC 状态码、延迟、客户端地址、request_id(可选)、完整方法名、状态文本。
延迟单位会自适应(ns / µs / ms / s),状态码到状态文本通过 codes.Code 映射。
request_id 行为(透传优先,否则生成)
- 读取 / 生成顺序:ctx 中已注入的 trace 字段(拦截器链外层已注入时)→ incoming metadata 的
x-request-id(客户端透传)→ 都没有则用 trace.DefaultGenerator 生成一个;
- 生成 / 提取到的 id 会注入 handler 的 ctx(Stream 通过包装
grpc.ServerStream 替换 Context()),
因此下游 trace 拦截器(logger/trace/middleware.GRPC*ServerInterceptor)的 Process 会
"先查 ctx 已有值" 从而复用同一个 id——access log、业务日志、响应头 x-request-id 三者完全一致;
- 客户端透传的
x-request-id 不会被生成逻辑覆盖丢弃;
- 响应头
x-request-id 的回写由下游 trace 拦截器负责(本拦截器只确保 ctx 有 id 并打 access log,
不重复回写以免响应头出现两个值)。若部署中未挂载 trace 拦截器,请自行在链路中回写响应头。
安装
go get gitee.com/hexug/go-tools/v2/grpc/custom_logger
快速开始
import (
"google.golang.org/grpc"
"gitee.com/hexug/go-tools/v2/grpc/custom_logger"
"gitee.com/hexug/go-tools/v2/logger"
)
log := logger.L() // 或自建 *logger.MyLogger
s := grpc.NewServer(
grpc.ChainUnaryInterceptor(custom_logger.GRPCLoggerInterceptor(log)),
grpc.ChainStreamInterceptor(custom_logger.GRPCStreamLoggerInterceptor(log)),
)
API
func GRPCLoggerInterceptor(log *logger.MyLogger) grpc.UnaryServerInterceptor
func GRPCStreamLoggerInterceptor(log *logger.MyLogger) grpc.StreamServerInterceptor
参数:
log:使用的 *logger.MyLogger 实例;调用时会通过 log.WithoutMeta() 移除时间/级别/路径,仅输出消息。
行为:
codes.OK:以 Info 级别打印;
codes.Canceled / codes.DeadlineExceeded / codes.NotFound:以 Warn 级别打印;
- 其他非
OK:以 Error 级别打印;
Unary 与 Stream 输出格式完全一致;Stream 版的耗时覆盖整个流的生命周期(含 handler 内部的收发循环)。
注意事项
- 客户端 IP 从
peer.FromContext(ctx) 中取,unknown 表示 ctx 中无 peer 信息;
- 拦截器内部不做日志聚合 / 限流,超高 QPS 时建议结合
rate 模块或采样后再写日志;
- 日志全部走
WithoutMeta() 输出,调用方需要自行保证 log 自身配置(写文件、JSON 等)满足生产要求。