链路追踪与可观测性

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│   Traces     │   │   Metrics    │   │    Logs      │
│  链路追踪    │   │  指标监控    │   │  结构化日志  │
├──────────────┤   ├──────────────┤   ├──────────────┤
│ OpenTelemetry│   │ Prometheus   │   │ logx (JSON)  │
│ → Jaeger     │   │ → Grafana    │   │ → ELK/Loki   │
└──────────────┘   └──────────────┘   └──────────────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                 trace_id 关联

Telemetry:
  Name: user-api               # 服务名称（在 Jaeger 中显示）
  Endpoint: jaeger:4317        # OTLP gRPC 端点
  Sampler: 1.0                 # 采样率 0.0 ~ 1.0
  Batcher: otlpgrpc            # otlpgrpc | otlphttp

// etc/config.go
type Config struct {
    rest.RestConf
    Telemetry trace.Config
}

version: "3"
services:
  jaeger:
    image: jaegertracing/all-in-one:1.57
    ports:
      - "16686:16686"   # Web UI
      - "4317:4317"     # OTLP gRPC（go-zero 使用）
      - "4318:4318"     # OTLP HTTP（可选）
    environment:
      - COLLECTOR_OTLP_ENABLED=true

Telemetry:
  Name: my-service
  Endpoint: localhost:4317     # 对应 OTLP gRPC 端口
  Sampler: 1.0
  Batcher: otlpgrpc

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
)

func (l *OrderLogic) CreateOrder(ctx context.Context) error {
    tracer := otel.Tracer("biz")
    ctx, span := tracer.Start(ctx, "create-order")
    defer span.End()

    span.SetAttributes(
        attribute.Int64("order_id", orderId),
        attribute.String("operation", "create"),
        attribute.Float64("amount", amount),
    )

    // 记录事件
    span.AddEvent("payment-verified", trace.WithAttributes(
        attribute.String("method", "wechat"),
    ))

    // 记录错误
    if err != nil {
        span.RecordError(err)
        span.SetStatus(codes.Error, err.Error())
    }

    // 业务逻辑...
}

Prometheus:
  Host: 0.0.0.0
  Port: 9090            # metrics 端口
  Path: /metrics

# 访问 metrics 端点
curl http://localhost:9090/metrics

# 输出示例：
# http_request_duration_ms_bucket{path="/user/login",le="100"} 1523
# http_request_error_total{path="/user/login",code="500"} 2

Prometheus: false

Log:
  ServiceName: user-api
  Mode: file
  Level: info
  Path: logs/user-api
  Encoding: json          # json | plain
  KeepDays: 7

import "github.com/zeromicro/go-zero/core/logx"

// 基础使用
logx.Info("user created")
logx.Infof("user %d created", userId)
logx.Error("failed to create user")

// 带 context（自动注入 trace_id）
logx.WithContext(ctx).Infow("order created",
    logx.Field("orderId", orderId),
    logx.Field("userId", userId),
)

{
  "@timestamp": "2026-07-10T10:30:00.000Z",
  "level": "info",
  "content": "order created",
  "trace": "3e2a9bc1f...",
  "span": "abc123...",
  "orderId": 123,
  "userId": 456
}

                       ┌──────────────┐
                       │   Client     │
                       └──────┬───────┘
                              │ HTTP / gRPC
                       ┌──────▼───────┐
                       │  API Gateway │
            ┌──────────┤  (go-zero)   ├──────────┐
            │          └──────┬───────┘          │
            │                 │                   │
       /metrics          自动埋点            结构化日志
            │                 │                   │
     ┌──────▼──────┐   ┌─────▼─────┐     ┌──────▼──────┐
     │ Prometheus  │   │   OTLP    │     │  File/ELK/  │
     │  采集指标   │   │ Collector │     │    Loki     │
     └──────┬──────┘   └─────┬─────┘     └──────┬──────┘
            │                 │                   │
     ┌──────▼──────┐   ┌─────▼─────┐     ┌──────▼──────┐
     │   Grafana   │   │  Jaeger   │     │  Grafana    │
     │   监控面板  │   │ 链路追踪  │     │  日志面板   │
     └─────────────┘   └───────────┘     └─────────────┘