logging-observability

核心用法

本 Skill 是一套完整的可观测性工程实践指南，围绕日志（Logs）、指标（Metrics）、追踪（Traces）三大支柱展开。核心用法包括：

1. 结构化日志实施：强制使用 JSON 格式输出，包含 timestamp、level、service、trace_id、span_id 等必需字段，通过异步上下文存储实现自动上下文传递
2. 分布式追踪配置：基于 OpenTelemetry 标准，使用 NodeSDK 初始化追踪器，通过 W3C Trace Context 协议在 HTTP/gRPC/消息队列间传播上下文，支持多种采样策略（概率采样、速率限制、尾部采样）
3. 指标体系建设：采用 RED 方法（Rate/Errors/Duration）监控服务端点，USE 方法（Utilization/Saturation/Errors）监控基础设施资源
4. 监控栈搭建：推荐 OTel Collector → Prometheus + Grafana + Loki + Jaeger 的开源组合，提供从采集到可视化的完整链路
5. 告警与仪表盘设计：定义 P1-P4 严重级别，遵循"告警症状而非原因"原则，配套 Overview Dashboard（全局战情室）和 Service Dashboard（单服务视图）两种模板

显著优点

• 标准先行：全面拥抱 OpenTelemetry 开放标准，避免厂商锁定，支持多云/混合云环境
• 生产就绪：提供可直接落地的代码示例（Pino/zerolog/zap 等高性能日志库选型）、配置模板和检查清单
• 安全内建：专设 PII/Secret 脱敏章节，明确"NEVER log passwords/tokens/API keys"等红线，包含 8 条反模式警示
• 成本意识：强调采样策略、日志级别动态调整、高基数标签规避等成本控制手段
• 全链路覆盖：从开发规范（结构化日志）到运维实践（告警疲劳预防）形成闭环

潜在缺点与局限性

• 无自动化能力：纯文档型 Skill，不提供代码生成或自动配置功能，需人工逐条实施
• 技术栈偏向：示例以 Node.js/TypeScript 为主，Python/Go/Rust 覆盖相对简略
• 云原生假设：默认假设 Kubernetes/Prometheus 环境，传统虚拟机或 Serverless 场景需额外适配
• 缺乏量化基准：未提供"多少 QPS 该选什么采样率"等具体数值建议
• T3 来源风险：来自个人开发者账号，无组织背书，长期维护承诺不明确

适合的目标群体

• SRE/平台工程师：搭建或重构可观测性基础设施
• 后端开发团队：制定团队日志规范、接入分布式追踪
• 技术负责人：审查现有系统的可观测性成熟度
• DevOps 转型企业：从传统监控向云原生可观测性迁移

使用风险

• 实施落差风险：文档建议与团队现有技术债可能存在冲突，需评估迁移成本
• 性能误配风险：不当的采样策略或日志级别可能导致数据丢失或存储成本激增
• 安全合规风险：尽管文档强调 PII 脱敏，实际实施时仍需结合企业合规要求定制
• 依赖项风险：OpenTelemetry 生态迭代较快，部分配置可能随版本更新失效

核心用法

本 Skill 是系统可观测性领域的综合性知识库，围绕日志（Logs）、指标（Metrics）、追踪（Traces）三大支柱提供标准化实践指南。核心用法包括：

1. 结构化日志：强制 JSON 格式输出，包含 timestamp、level、service、trace_id、span_id 等必填字段，支持通过异步上下文存储实现自动字段继承
2. 分布式追踪：基于 OpenTelemetry 实现跨服务链路追踪，涵盖自动埋点、手动 Span 创建、W3C Trace Context 传播及多种采样策略（概率采样、速率限制、尾部采样）
3. 指标监控：采用 RED 方法（Rate/Errors/Duration）监控服务端点，USE 方法（Utilization/Saturation/Errors）监控基础设施资源
4. 告警与可视化：提供分级告警设计（P1-P4）、告警疲劳预防策略，以及 Grafana 仪表板的最佳实践模板

显著优点

• 零技术债风险：纯 Markdown 文档，无可执行代码，无依赖引入，可直接安全使用
• 标准化框架：整合行业主流标准（OpenTelemetry、Prometheus、RED/USE 方法论），避免厂商锁定
• 安全内置：明确强调 PII 脱敏、密钥保护、高基数标签规避等安全合规要求
• 实操性强：提供多语言代码示例（TypeScript/Go/Python/Rust）和可直接参考的配置模板
• 告警设计科学：强调症状导向、多窗口多燃烧率、runbook 关联等 SRE 最佳实践

潜在局限

• 来源可信度限制：维护者为个人开发者（wpank），通过社区框架分发，属于 T3 级别来源，建议生产环境应用前对照官方文档验证
• 静态知识更新滞后：Observability 领域演进较快（如 OpenTelemetry 协议版本迭代），需用户主动关注上游更新
• 配置需场景适配：文档中的采样率、告警阈值、保留策略等参数需根据实际数据量和业务特性调整，不宜直接复制
• 无自动化能力：仅提供指导原则，不涉及自动部署、配置生成或运行时检测功能

适合人群

• SRE / DevOps 工程师：构建或优化可观测性平台
• 后端开发工程师：在应用层正确埋点、日志分级、追踪集成
• 技术负责人：制定团队日志规范、告警策略、监控体系架构
• 安全合规人员：审查日志脱敏、敏感数据处理流程

常规风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| 配置误用 | 直接复制示例配置导致采样不足或告警风暴 | 测试环境先行验证，根据流量调整参数 |

| 合规遗漏 | PII 脱敏配置不完整导致日志泄露 | 建立敏感字段清单，使用自动化扫描验证 |

| 高基数爆炸 | 将 user_id/request_id 误作指标标签 | 严格遵循文档反模式清单，代码审查时专项检查 |

| 追踪断裂 | 异步流程未传播 trace context | 在消息队列、定时任务等场景显式序列化 traceparent |