可观测性 on 姚玉亮的网络日志

线上问题排查方法论：从日志、链路到监控

Sun, 19 Jul 2026 10:30:00 +0800

一个报错，横跨四五个服务

做后端这些年，线上问题排查花掉的时间不比写新功能少。

在某 SaaS 公司时，宠物医疗 SaaS 系统从 fasthttp C/S 迁到 go-zero B/S，微服务一多，一个"医生开不了处方"的报错可能横跨网关、鉴权、处方、HIS 对接四五个服务。后来做 AI 数据平台，知识库问答服务和数据集管理服务又多了 LLM 调用、向量化、Temporal Worker 这些新组件，问题形态更杂。

坑踩得够多之后，我形成了一套固定的排障顺序：先看监控定边界，再查链路定位置，最后翻日志看细节。顺序反了，就是在大海里捞针。

先看监控：把边界画出来

告警来了先别急着登机器，先在 Grafana 上回答三个问题：影响面多大（单用户还是全量）、从什么时候开始（发版后还是突发）、哪个指标异常（错误率、延迟、CPU、内存、队列堆积）。

我们在 KubeSphere 上给每个服务配了 RED 指标（Rate、Errors、Duration），业务侧再加关键看板：统一支付平台看支付成功率和回调延迟，统一认证中心看登录失败率和各 Provider（腾讯云 SMS/SES）的错误码分布，知识库问答服务看首 token 建立延迟和各 LLM 供应商的超时率。

一张 dashboard，能先把"是不是我的问题、是我的问题大概在哪"筛掉八成。

再查链路：定位到那一步

确定是某个服务的问题后，用 trace_id 把整条请求链拉出来。我们在 go-zero 和 Hertz 里都接了 gRPC 拦截器和 HTTP middleware，把 trace_id 从入口一路透传到下游、MQ 消费者、Temporal Workflow。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// Hertz 中统一的 trace + 日志中间件
func AccessLog() app.HandlerFunc {
 return func(ctx context.Context, c *app.RequestContext) {
 traceID := string(c.Request.Header.Get("X-Trace-Id"))
 if traceID == "" {
 traceID = snowflake.NextString()
 c.Request.Header.Set("X-Trace-Id", traceID)
 }
 c.Response.Header.Set("X-Trace-Id", traceID)

 start := time.Now()
 c.Next(ctx)

 log.Info("http access",
 zap.String("trace_id", traceID),
 zap.String("method", string(c.Method())),
 zap.String("path", string(c.Path())),
 zap.Int("status", c.Response.StatusCode()),
 zap.Duration("cost", time.Since(start)),
 )
 }
}

拿到 trace_id 去 Jaeger 看瀑布图，一眼能看出哪个 span 慢、哪个 span 报错。AI 场景里我特意把对 LLM 的调用、向量检索、S3 上传都包成独立 span，不然一个"回答超时"，你根本分不清是模型慢还是检索慢。

最后翻日志：看为什么

trace 定位到具体服务和时段后，去 ELK 用 trace_id: "xxx" 精确捞日志。

我们的日志规范是：顶层打印请求入参和最终错误，中间层只追加上下文、不重复打错误，错误用 zap.Error(err) 带堆栈。一条合格的错误日志，应该能直接回答"什么操作、什么入参、为什么失败"。

四条规矩

第一，日志别瞎打。早期有人在循环里打全量文档内容，一次解析任务日志几百 MB，ELK 直接被打爆。后来定了规矩：DEBUG 级别打细节，生产默认 INFO；大对象只打 ID 和长度；敏感字段（手机号、密钥）一律脱敏。统一认证中心里这是红线。

第二，告警要可收敛。每个错误都告警等于没有告警。按服务 + 错误类型聚合，5 分钟内同类错误只发一条，再配升级策略：错误率超阈值且持续 10 分钟才打电话。夜间告警的质量，直接决定你能不能睡个整觉。

第三，异步任务的 trace 要手动续上。MQ 消费者和 Temporal Workflow 是新的执行上下文，trace_id 不会自动传过去，必须生产端塞进消息体、消费端取出来注入 context。这块漏了，异步链路就是断的，排障时最痛苦。

第四，回滚优先于根因。KubeSphere 容器化部署后，回滚 5 分钟内搞定。发现是发版引起的问题，第一反应是回滚，不是在线上 debug。业务恢复之后再慢慢查根因，顺序不能反。

后来

排障能力拼的不是谁见过的错误多，而是有没有一套不依赖运气的检索路径。监控告诉你"哪里不对"，链路告诉你"在哪一步不对"，日志告诉你"具体为什么不对"。三件事平时建设好，告警响的时候才不会慌。

Jaeger 在微服务排障中的真实案例

Sun, 26 Oct 2025 10:30:00 +0800

病历保存偶尔要 5 秒

在某 SaaS 公司时期，我们把宠物医疗 SaaS 系统从 fasthttp C/S 架构迁到 go-zero B/S，服务拆成了十多个 gRPC 微服务，接了 Jaeger 做分布式链路追踪。

上线后医院端反馈：病历保存偶尔要 5 秒以上。高峰期尤其明显，又无法稳定复现。日志分散在各个服务里，光看 Nginx access log，根本判断不出卡在哪一跳。

每一跳都留 span

埋点用 OpenTelemetry SDK 统一做。gRPC unary interceptor 在服务端自动创建 span，客户端拦截器负责透传 trace context；Jaeger Collector 收 span 后写入 ES 后端，在 Jaeger UI 里按 operation 和耗时过滤。

关键一步是把 DB 查询、Redis 调用、外部 AI 影像判读接口都包成子 span，瀑布图才能真实反映每一跳的耗时。

埋点代码

初始化 TracerProvider，采样率先设 10%：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


func InitTracer(ctx context.Context, serviceName, endpoint string) (*sdktrace.TracerProvider, error) {
 conn, err := grpc.DialContext(ctx, endpoint,
 grpc.WithTransportCredentials(insecure.NewCredentials()),
 )
 if err != nil {
 return nil, err
 }
 exp, err := otlptracegrpc.New(ctx, otlptracegrpc.WithGRPCConn(conn))
 if err != nil {
 return nil, err
 }
 tp := sdktrace.NewTracerProvider(
 sdktrace.WithBatcher(exp),
 sdktrace.WithResource(resource.NewWithAttributes(
 semconv.SchemaURL,
 semconv.ServiceName(serviceName),
 )),
 sdktrace.WithSampler(
 sdktrace.ParentBased(sdktrace.TraceIDRatioBased(0.1)),
 ),
 )
 otel.SetTracerProvider(tp)
 return tp, nil
}

gRPC 服务端拦截器，出错时记进 span：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


func TracingInterceptor(ctx context.Context, req any,
 info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
 tracer := otel.Tracer("grpc-server")
 ctx, span := tracer.Start(ctx, info.FullMethod)
 defer span.End()
 resp, err := handler(ctx, req)
 if err != nil {
 span.RecordError(err)
 span.SetStatus(codes.Error, err.Error())
 }
 return resp, err
}

DB 查询也挂上 span，这样瀑布图里能看到每一次落库：

1
2
3


ctx, span := tracer.Start(ctx, "db.patient.save")
defer span.End()
err := db.WithContext(ctx).Create(&patient).Error

minDuration=3s，根因一眼可见

那次 5 秒卡顿，我们在 Jaeger UI 里用 minDuration=3s 过滤，把所有超过 3 秒的 trace 捞出来，根因基本就摆在瀑布图上了。

病历保存链路会同步调用 AI 影像判读服务，这个服务冷启动时加载模型要 4 秒多，而前端在同步等结果。改法是把 AI 调用改成异步落库加回调通知，改完 P99 立刻降到几百毫秒。

其他几个坑

第一，采样率不要一刀切。登录、支付这种核心链路我用 100% 采样（通过 span attribute 标记），普通查询 10%，不然 Jaeger 后端扛不住。

第二，context 透传是重灾区。go-zero 里有些自定义 goroutine 没把 ctx 传进去，trace 直接断链。我们规定所有异步任务必须显式接 context；跨 Kafka/RabbitMQ 时，用 otel.GetTextMapPropagator().Inject 把 carrier 塞进消息 header。

第三，span 不是越多越好。一个 for 循环里每条 SQL 都开 span，UI 会卡死，批量操作只开一个聚合 span。

第四，别把大对象塞进 span attribute，请求体只记摘要和 ID，不然 Jaeger 查询本身会很慢。

后来

那次排查之后我养成一个习惯：任何一次跨服务的慢请求，先开 Jaeger 看瀑布图，而不是翻日志。链路追踪的价值不在"接了"，而在用它解决具体问题。Trace 就是微服务时代的调试器，没有它，十多个 gRPC 服务之间的调用就是一个黑盒。

封面图：somegeekintn / Flickr · CC BY 2.0

用 Zap + ELK 构建 Go 服务结构化日志体系

Sat, 11 Oct 2025 10:30:00 +0800

一个请求，几十个 Pod

我之前主导过几个 Go 服务：统一认证中心、统一支付平台、知识库问答服务。早期都用标准 log 包打文本日志，服务之间走 gRPC，一个请求出了问题，就要在几十个 Pod 的日志里来回 grep，trace_id 还经常对不上，排障体验很差。

后来我们下决心，统一到 Zap 加 ELK 的结构化日志体系。

一条日志的旅程

大方向是这样的：Zap 用 NewProduction 的 JSON Encoder 出结构化日志，统一写 stdout；Filebeat 负责采集，交给 Logstash 清洗后写入 Elasticsearch；查问题的时候，在 Kibana 里按 trace_id 聚合查询。

trace_id、request_id、tenant_id 这些字段通过 context.Context 注入。Gin 中间件在 HTTP 入口生成或透传 trace_id，gRPC 拦截器从 metadata 里取出来挂到 logger 上，跨了进程也不丢。

知识库问答服务的流式接口还多打了一个会话 ID 字段，要复现某一轮对话，拿 ID 直接过滤就行。

Logger 初始化

生产和开发两套配置，生产开采样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


func NewLogger(env string) *zap.Logger {
 var cfg zap.Config
 if env == "production" {
 cfg = zap.NewProductionConfig()
 cfg.EncoderConfig.TimeKey = "ts"
 cfg.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
 cfg.Sampling = &zap.SamplingConfig{
 Initial: 100,
 Thereafter: 100,
 }
 } else {
 cfg = zap.NewDevelopmentConfig()
 cfg.EncoderConfig.EncodeLevel = zapcore.CapitalColorLevelEncoder
 }
 lg, err := cfg.Build(zap.AddCallerSkip(1))
 if err != nil {
 panic(err)
 }
 return lg
}

trace_id 从哪来

Gin 中间件把 trace_id 塞进 context，顺手打一条访问日志：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


const TraceIDHeader = "X-Trace-Id"

func AccessLog(lg *zap.Logger) gin.HandlerFunc {
 return func(c *gin.Context) {
 start := time.Now()
 tid := c.GetHeader(TraceIDHeader)
 if tid == "" {
 tid = uuid.NewString()
 }
 c.Writer.Header().Set(TraceIDHeader, tid)
 c.Set("logger", lg.With(
 zap.String("trace_id", tid),
 zap.String("path", c.Request.URL.Path),
 ))
 c.Next()
 lg.Info("http.access",
 zap.String("trace_id", tid),
 zap.Int("status", c.Writer.Status()),
 zap.Duration("latency", time.Since(start)),
 zap.String("client_ip", c.ClientIP()),
 )
 }
}

业务代码里通过 helper 取带字段的 logger：

1
2
3
4
5
6
7
8


type ctxKey struct{}

func FromContext(ctx context.Context) *zap.Logger {
 if l, ok := ctx.Value(ctxKey{}).(*zap.Logger); ok {
 return l
 }
 return zap.L()
}

gRPC 服务端拦截器从 metadata 透传 trace_id，保证跨进程能串起来，实现思路和上面类似，不展开了。

五个坑

第一个是 logger 选型。SugaredLogger 比强类型 Logger 慢约三成，知识库问答服务流式输出这种热路径上我们坚持用 Logger，只在脚本和启动阶段用 Sugared。

第二，生产环境一定要开 Sampling。有点反直觉，日志系统自己也会被日志打垮：下游一次故障触发的错误风暴，足以把 ES 打爆。Initial 和 Thereafter 按服务实际 QPS 调。

第三，脱敏是红线。AppSecret、RSA 私钥、Authorization 头，严禁原样打出来。统一认证中心里我们写了脱敏 hook，对 password、secret、token 这几个字段统一 mask。

第四，采集链路用 Filebeat，别让应用直连 ES，Pod 重启也不丢缓冲日志，稳得多。要记得配 multiline，把 panic 堆栈合并成一条。

第五，日志级别要能动态调。zap.AtomicLevel 配合配置中心，线上出问题时临时把某个服务调到 DEBUG，不用发版。

后来

这套体系搭好之后，最直观的变化是排障速度：统一认证中心跨服务的登录问题，从几十分钟缩到了分钟级。回头看，结构化日志的难点不在换个日志库，而在两件事：字段规范（trace_id、error、latency、biz_code）和上下游透传。简单说，Zap 决定"打什么、怎么打"，ELK 解决"去哪查"。

封面图：dfulmer / Flickr · CC BY 2.0

基于 Jaeger 的全链路追踪：从 gRPC 到 HTTP 的上下文透传

Sat, 07 Oct 2023 10:30:00 +0800

三个工程师查了两小时

宠物医疗 SaaS 拆成微服务后，排查一次挂号请求要跨 API 网关、clinic-rpc、payment-rpc、inventory-rpc 四个服务。最开始出了问题只能靠日志拼时间线：每个服务打印自己的 requestId，但请求一经过 gRPC 调用，requestId 就断了，根本串不起来。

有一次线上出问题，“挂号后扣费失败”，三个工程师对着日志查了两个小时，才定位到是 inventory-rpc 超时导致的回滚失败。小问题查成这样，必须上全链路追踪了。选型用了 Jaeger，因为它兼容 OpenTracing 标准，go-zero 也有内置支持。

traceId 怎么透传

核心思路一句话能说完：在入口层生成 traceId，通过 HTTP Header 和 gRPC metadata 一路传下去，每个服务处理请求时从 context 里取出 SpanContext，创建子 Span 上报给 Jaeger Agent。

go-zero 自带了 trace 包，在 API 层配置一个 Jaeger 上报地址即可自动注入：

1
2
3
4
5
6
7
8
9


# api/etc/clinic-api.yaml
Name: clinic-api
Host: 0.0.0.0
Port: 8888
Telemetry:
 Name: clinic-api
 Endpoint: http://jaeger-agent:14268/api/traces
 Sampler: 1.0
 Batcher: jaeger

但 go-zero 内置的 trace 只覆盖它自己生成的 gRPC 客户端。我们有些连接是直接用 grpc.Dial 创建的，这种就得手动加拦截器。服务端拦截器负责从 incoming context 提取 SpanContext 并创建服务端 Span：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


func UnaryServerInterceptor(tracer opentracing.Tracer) grpc.UnaryServerInterceptor {
 return func(ctx context.Context, req interface{},
 info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {

 md, ok := metadata.FromIncomingContext(ctx)
 var spanCtx opentracing.SpanContext
 if ok {
 // 从 gRPC metadata 的 uber-trace-id 提取
 if carriers, ok := md["uber-trace-id"]; ok && len(carriers) > 0 {
 textMap := opentracing.TextMapCarrier{"uber-trace-id": carriers[0]}
 spanCtx, _ = tracer.Extract(opentracing.TextMap, textMap)
 }
 }

 span := tracer.StartSpan(
 info.FullMethod,
 ext.RPCServerOption(spanCtx),
 )
 defer span.Finish()

 ctx = opentracing.ContextWithSpan(ctx, span)
 resp, err := handler(ctx, req)
 if err != nil {
 ext.Error.Set(span, true)
 span.LogKV("event", "error", "message", err.Error())
 }
 return resp, err
 }
}

客户端拦截器反过来，把当前 SpanContext 注入 outgoing metadata：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


func UnaryClientInterceptor(tracer opentracing.Tracer) grpc.UnaryClientInterceptor {
 return func(ctx context.Context, method string,
 req, reply interface{}, cc *grpc.ClientConn,
 invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {

 span, ctx := opentracing.StartSpanFromContext(ctx, method)
 defer span.Finish()

 md, _ := metadata.FromOutgoingContext(ctx)
 if md == nil {
 md = metadata.New(nil)
 }
 carrier := opentracing.TextMapCarrier{}
 _ = tracer.Inject(span.Context(), opentracing.TextMap, carrier)
 for k, v := range carrier {
 md.Set(k, v)
 }
 ctx = metadata.NewOutgoingContext(ctx, md)
 return invoker(ctx, method, req, reply, cc, opts...)
 }
}

HTTP 层我们在 Gin 网关加了一个中间件，从请求头取 Uber-Trace-Id，没有就新开根 Span：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func TracingMiddleware(tracer opentracing.Tracer) gin.HandlerFunc {
 return func(c *gin.Context) {
 spanCtx, _ := tracer.Extract(
 opentracing.HTTPHeaders,
 opentracing.HTTPHeadersCarrier(c.Request.Header),
 )
 span := tracer.StartSpan(
 c.Request.URL.Path,
 ext.RPCServerOption(spanCtx),
 )
 defer span.Finish()

 ctx := opentracing.ContextWithSpan(c.Request.Context(), span)
 c.Request = c.Request.WithContext(ctx)
 c.Next()
 }
}

链路是在哪里断的

第一个断点是异步 goroutine。有些逻辑起 goroutine 异步处理，直接用了 context.Background()，Span 链就断了。我们的规矩是异步任务必须从父 context 派生，但要 detach，不能直接用父 ctx，因为父 ctx 在 HTTP 返回后会被 cancel。我封装了一个 detachContext，只保留 trace 信息、不继承 cancel 信号。

第二个是采样率。生产环境 100% 采样，Jaeger 后端和网络的压力都不小。我们改成 10% 采样，错误请求强制 100%（在拦截器里判断 err != nil 时设置 sampling.priority=1）。

第三个是 B3 和 Jaeger 原生头的兼容。老版本 Istio sidecar 用的是 B3 头（X-B3-TraceId），我们应用层用的是 uber-trace-id，两边串不起来。统一改成 W3C TraceContext（traceparent 头）后解决了这个问题，也是未来的标准方向。

值不值

全链路追踪的价值不在平时，而在故障时：它把跨服务的黑盒变成可观测的调用链。关键是 context 透传不能有断点，HTTP 入口、gRPC 双向、异步 goroutine 都要覆盖到。踩完这些坑之后，宠物医疗 SaaS 排查一次跨服务故障的平均时间，从小时级降到了分钟级。

封面图：dolbinator1000 / Flickr · CC BY 2.0