1
// 传统日志：无法搜索、无法关联
2
log.Printf("user %d created order %d", userID, orderID)
3

4
// 结构化日志：可搜索、可关联、可解析
5
logger.Info("order created",
6
    zap.Int64("user_id", userID),
7
    zap.Int64("order_id", orderID),
8
    zap.String("trace_id", traceID),
9
    zap.Duration("duration", elapsed),
10
)

1
# Python 结构化日志
2
import structlog
3

4
logger = structlog.get_logger()
5

6
# 传统日志
7
logger.info(f"Processing order {order_id} for user {user_id}")
8

9
# 结构化日志
10
logger.info("order.processing",
11
    order_id=order_id,
12
    user_id=user_id,
13
    items=len(items),
14
    total_amount=total,
15
    trace_id=trace_id,
16
)

1
// 在关键操作上添加 Span 注解
2
func (s *OrderService) CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error) {
3
    ctx, span := otel.Tracer("order").Start(ctx, "CreateOrder")
4
    defer span.End()
5

6
    // 添加业务属性
7
    span.SetAttributes(
8
        attribute.Int64("user.id", req.UserID),
9
        attribute.Int("items.count", len(req.Items)),
10
        attribute.String("currency", req.Currency),
11
    )
12

13
    // 步骤 1：验证库存
14
    ctx, validateSpan := otel.Tracer("order").Start(ctx, "ValidateInventory")
15
    err := s.inventory.Validate(ctx, req.Items)
16
    validateSpan.End()
17
    if err != nil {
18
        span.SetStatus(codes.Error, err.Error())
19
        span.RecordError(err)
20
        return nil, err
21
    }
22

23
    // 步骤 2：计算价格
24
    ctx, priceSpan := otel.Tracer("order").Start(ctx, "CalculatePrice")
25
    total := s.pricing.Calculate(ctx, req.Items)
26
    priceSpan.SetAttributes(attribute.Float64("order.total", total))
27
    priceSpan.End()
28

29
    // 步骤 3：持久化
30
    order, err := s.repo.Save(ctx, &Order{
31
        UserID: req.UserID,
32
        Items:  req.Items,
33
        Total:  total,
34
    })
35
    if err != nil {
36
        span.RecordError(err)
37
        return nil, err
38
    }
39

40
    span.SetAttributes(attribute.Int64("order.id", order.ID))
41
    return order, nil
42
}

1
// RED 方法：Rate, Errors, Duration
2
var (
3
    orderCreated = otel.Meter("order").Int64Counter("order.created",
4
        metric.WithDescription("Number of orders created"),
5
    )
6
    orderDuration = otel.Meter("order").Float64Histogram("order.duration",
7
        metric.WithDescription("Order creation duration"),
8
        metric.WithUnit("ms"),
9
    )
10
    orderErrors = otel.Meter("order").Int64Counter("order.errors",
11
        metric.WithDescription("Number of order creation errors"),
12
    )
13
)
14

15
func (s *OrderService) CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error) {
16
    start := time.Now()
17

18
    order, err := s.createOrderInternal(ctx, req)
19

20
    // 记录指标
21
    elapsed := time.Since(start).Milliseconds()
22
    orderDuration.Record(ctx, float64(elapsed),
23
        metric.WithAttributes(attribute.String("currency", req.Currency)),
24
    )
25

26
    if err != nil {
27
        orderErrors.Add(ctx, 1,
28
            metric.WithAttributes(attribute.String("error.type", classifyError(err))),
29
        )
30
    } else {
31
        orderCreated.Add(ctx, 1)
32
    }
33

34
    return order, err
35
}

1
// 传统错误处理：丢失上下文
2
func (s *Service) Process(ctx context.Context, id int64) error {
3
    order, err := s.repo.GetOrder(ctx, id)
4
    if err != nil {
5
        return err  // "sql: no rows in result set" — 哪个订单？哪个查询？
6
    }
7
    // ...
8
}
9

10
// 结构化错误：保留完整上下文
11
func (s *Service) Process(ctx context.Context, id int64) error {
12
    order, err := s.repo.GetOrder(ctx, id)
13
    if err != nil {
14
        return fmt.Errorf("get order %d: %w", id, err)
15
        // "get order 12345: sql: no rows in result set" — 现在知道是哪个订单了
16
    }
17
    // ...
18
}

1
// 业务错误类型
2
type BusinessError struct {
3
    Code     string                 // 错误码："ORDER_NOT_FOUND"
4
    Message  string                 // 人类可读消息
5
    Metadata map[string]interface{} // 结构化元数据
6
    Cause    error                  // 原始错误
7
}
8

9
func (e *BusinessError) Error() string {
10
    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
11
}
12

13
func (e *BusinessError) Unwrap() error {
14
    return e.Cause
15
}
16

17
// 使用示例
18
func (s *OrderService) GetOrder(ctx context.Context, id int64) (*Order, error) {
19
    order, err := s.repo.GetOrder(ctx, id)
20
    if err != nil {
21
        if errors.Is(err, sql.ErrNoRows) {
22
            return nil, &BusinessError{
23
                Code:    "ORDER_NOT_FOUND",
24
                Message: fmt.Sprintf("Order %d not found", id),
25
                Metadata: map[string]interface{}{
26
                    "order_id": id,
27
                    "user_id":  ctx.Value(userIDKey),
28
                },
29
                Cause: err,
30
            }
31
        }
32
        return nil, &BusinessError{
33
            Code:    "ORDER_FETCH_FAILED",
34
            Message: "Failed to fetch order",
35
            Metadata: map[string]interface{}{"order_id": id},
36
            Cause: err,
37
        }
38
    }
39
    return order, nil
40
}

1
// 错误处理器：自动记录到日志和追踪
2
func HandleError(ctx context.Context, err error) {
3
    var bizErr *BusinessError
4
    if errors.As(err, &bizErr) {
5
        // 结构化日志
6
        logger.Error("business error",
7
            zap.String("code", bizErr.Code),
8
            zap.String("message", bizErr.Message),
9
            zap.Any("metadata", bizErr.Metadata),
10
        )
11

12
        // 追踪记录
13
        span := trace.SpanFromContext(ctx)
14
        span.SetStatus(codes.Error, bizErr.Code)
15
        span.SetAttributes(
16
            attribute.String("error.code", bizErr.Code),
17
            attribute.String("error.message", bizErr.Message),
18
        )
19
        span.RecordError(bizErr)
20

21
        // 指标记录
22
        errorCounter.Add(ctx, 1,
23
            metric.WithAttributes(attribute.String("error.code", bizErr.Code)),
24
        )
25
    }
26
}

1
// 业务指标：比技术指标更有价值
2
var (
3
    // 订单指标
4
    ordersCreated = meter.Int64Counter("business.orders.created")
5
    ordersCompleted = meter.Int64Counter("business.orders.completed")
6
    orderValue = meter.Float64Histogram("business.orders.value",
7
        metric.WithUnit("USD"),
8
    )
9

10
    // 支付指标
11
    paymentsProcessed = meter.Int64Counter("business.payments.processed")
12
    paymentLatency = meter.Float64Histogram("business.payments.latency",
13
        metric.WithUnit("ms"),
14
    )
15

16
    // 用户指标
17
    activeUsers = meter.Int64UpDownCounter("business.users.active")
18
    userRegistrations = meter.Int64Counter("business.users.registered")
19
)
20

21
// 在业务逻辑中记录
22
func (s *OrderService) CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error) {
23
    order, err := s.createOrder(ctx, req)
24
    if err != nil {
25
        return nil, err
26
    }
27

28
    // 记录业务指标
29
    ordersCreated.Add(ctx, 1,
30
        attribute.String("market", req.Market),
31
        attribute.String("channel", req.Channel),
32
    )
33
    orderValue.Record(ctx, float64(order.Total),
34
        attribute.String("currency", order.Currency),
35
    )
36

37
    return order, nil
38
}

1
# 业务指标告警规则
2
# 订单创建速率下降 50%
3
- alert: OrderRateDrop
4
  expr: |
5
    rate(business_orders_created_total[5m])
6
    <
7
    0.5 * rate(business_orders_created_total[5m] offset 1h)
8
  for: 10m
9

10
# 支付成功率低于 99%
11
- alert: PaymentSuccessRateLow
12
  expr: |
13
    rate(business_payments_processed_total{status="success"}[5m])
14
    /
15
    rate(business_payments_processed_total[5m])
16
    < 0.99
17
  for: 5m
18

19
# 平均订单金额异常
20
- alert: AbnormalOrderValue
21
  expr: |
22
    histogram_avg(business_orders_value)
23
    >
24
    2 * histogram_avg(business_orders_value offset 1d)
25
  for: 15m

1
## 可观测性代码审查清单
2

3
### 日志
4
- [ ] 使用结构化日志（非 fmt.Println）
5
- [ ] 包含 trace_id 和 span_id
6
- [ ] 日志级别正确（Debug/Info/Warn/Error）
7
- [ ] 不包含敏感信息（密码、token）
8

9
### 错误
10
- [ ] 错误包含上下文信息（哪个实体、哪个操作）
11
- [ ] 使用 %w 包装错误（保留错误链）
12
- [ ] 定义业务错误码（非通用 "internal error"）
13
- [ ] 错误记录到追踪系统
14

15
### 指标
16
- [ ] 关键操作有 Counter（调用次数）
17
- [ ] 关键操作有 Histogram（延迟分布）
18
- [ ] 指标标签基数合理（< 10 个值）
19
- [ ] 有业务指标（非只有 HTTP 指标）
20

21
### 追踪
22
- [ ] 关键函数有 Span
23
- [ ] Span 包含业务属性
24
- [ ] 上下文正确传播（ctx 传递）
25
- [ ] 跨服务调用有追踪传播

1
// 测试：验证关键操作产生正确的信号
2
func TestCreateOrder_Observability(t *testing.T) {
3
    // 设置测试追踪提供者
4
    provider := tracetest.NewTracerProvider()
5
    tracer := provider.GetTracer("test")
6

7
    // 执行操作
8
    ctx, span := tracer.Start(context.Background(), "test")
9
    _, err := service.CreateOrder(ctx, validRequest)
10
    span.End()
11

12
    // 验证产生了正确的 Span
13
    spans := provider.GetSpans()
14
    assert.Len(t, spans, 3)  // test + CreateOrder + Save
15

16
    // 验证 CreateOrder Span 的属性
17
    orderSpan := spans[1]
18
    assert.Equal(t, "CreateOrder", orderSpan.Name)
19
    assert.Equal(t, int64(12345), orderSpan.Attributes["user.id"])
20
    assert.Equal(t, 3, orderSpan.Attributes["items.count"])
21

22
    // 验证错误被记录
23
    if err != nil {
24
        assert.Equal(t, codes.Error, orderSpan.Status.Code)
25
        assert.Equal(t, "ORDER_NOT_FOUND", orderSpan.Attributes["error.code"])
26
    }
27
}