为服务建立可观测性与性能治理：配置结构化日志…

当需要给应用或分布式服务添加监控/可观测性、用日志/指标/追踪排查生产问题，或进行负载测试、性能剖析与容量预测时使用。

适用场景

解决思路

1. 先评估：识别需要监控的内容：SLIs、关键路径、业务指标。
2. 插桩：向应用添加日志、指标和追踪。
3. 采集：配置聚合与存储（Prometheus scrape、log shipper、OTLP endpoint）；继续前验证数据已到达。
4. 可视化：使用 RED（Rate/Errors/Duration）或 USE（Utilization/Saturation/Errors）方法构建 dashboard。
5. 告警：在关键路径上定义阈值告警和异常告警；上线前验证不会产生误报洪流。
6. 使用 Pino 做结构化日志：import pino；const logger = pino({ level: 'info' })。
7. 记录日志时使用结构化字段并包含 correlation ID，例如 logger.info({ requestId: req.id, userId: req.user.id, durationMs: elapsed }, "order.created")。
8. 避免字符串插值且无 correlation 的日志，例如 console.log(`Order created for user ${userId}`)。
9. Prometheus 指标：从 prom-client 引入 Counter、Histogram、register。
10. 定义 Counter：name: 'http_requests_total'，help: 'Total HTTP requests'，labelNames: ['method', 'route', 'status']。
11. 定义 Histogram：name: 'http_request_duration_seconds'，help: 'HTTP request latency'，labelNames: ['method', 'route']，buckets: [0.05, 0.1, 0.3, 0.5, 1, 2, 5]。
12. 为路由插桩：在中间件中用 httpDuration.startTimer({ method: req.method, route: req.path })；在 res.on('finish') 中 httpRequests.inc({ method: req.method, route: req.path, status: res.statusCode }) 并调用 end()。
13. 暴露 scrape endpoint：app.get('/metrics', async (req, res) => { res.set('Content-Type', register.contentType); res.end(await register.metrics()); })。
14. OpenTelemetry 追踪：配置 NodeSDK，使用 OTLPTraceExporter({ url: 'http://jaeger:4318/v1/traces' })；调用 sdk.start()。
15. 获取 tracer：const tracer = trace.getTracer('order-service')。
16. 在关键操作中手动创建 span：processOrder 中 tracer.startSpan('order.process')；span.setAttribute('order.id', orderId)。
17. span 成功时 span.setStatus({ code: SpanStatusCode.OK })；异常时 span.recordException(err) 并 span.setStatus({ code: SpanStatusCode.ERROR }) 后 throw；finally 中 span.end()。
18. 创建 Prometheus 告警规则组：groups: - name: api.rules。
19. 定义 HighErrorRate 告警：expr 为 rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05；for: 2m；labels.severity: critical；annotations.summary: "Error rate above 5% on {{ $labels.route }}"。
20. k6 负载测试：定义 options.stages：{ duration: '1m', target: 50 }（ramp up）、{ duration: '5m', target: 50 }（sustained load）、{ duration: '1m', target: 0 }（ramp down）。
21. 设置 k6 thresholds：http_req_duration: ['p(95)<500']；http_req_failed: ['rate<0.01']。
22. 编写 k6 default 函数：http.get('https://api.example.com/orders')；check(res, { 'status is 200': (r) => r.status === 200 })；sleep(1)。
23. 涉及日志时加载 references/structured-logging.md（Pino、JSON logging）。
24. 涉及指标时加载 references/prometheus-metrics.md（Counter、Histogram、Gauge）。
25. 涉及追踪时加载 references/opentelemetry.md（OpenTelemetry、spans）。
26. 涉及告警时加载 references/alerting-rules.md（Prometheus alerts）。
27. 涉及 dashboard 时加载 references/dashboards.md（RED/USE method、Grafana）。
28. 涉及性能测试时加载 references/performance-testing.md（Load testing、k6、Artillery、benchmarks）。
29. 涉及 profiling 时加载 references/application-profiling.md（CPU/memory profiling、bottlenecks）。
30. 涉及容量规划时加载 references/capacity-planning.md（Scaling、forecasting、budgets）。
31. MUST DO：使用结构化日志（JSON）。
32. MUST DO：包含 request IDs 以进行关联。
33. MUST DO：为关键路径设置告警。
34. MUST DO：监控业务指标，而不只是技术指标。
35. MUST DO：使用合适的指标类型（counter/gauge/histogram）。
36. MUST DO：实现 health check endpoints。
37. MUST NOT DO：不要记录敏感数据（passwords、tokens、PII）。
38. MUST NOT DO：不要对每个错误都告警（导致 alert fatigue）。
39. MUST NOT DO：不要在日志中使用字符串插值（应使用结构化字段）。
40. MUST NOT DO：不要在分布式系统中跳过 correlation IDs。

适用边界 · 注意事项

• 没有可观测性采集、存储、告警或追踪后端，且无法部署或接入 Prometheus、Grafana、OTLP、Jaeger 等基础设施时。
• 一次性脚本、本地小工具或没有关键路径、长期稳定性与性能治理需求时。
• 无法对日志、指标、追踪中的敏感数据（passwords、tokens、PII）做脱敏与合规处理时。