关于 observability-fundamentals
面向工程师的概念性技能，介绍 Honeycomb 的可观测性方法。内容涵盖宽事件、维度分析和调查循环，并说明如何将埋点选择用于根因分析。
主要功能
- 01解释宽事件与 Span
- 02区分事件、指标和日志
- 03说明基数与维度
- 04概述调查分析循环
- 05关联埋点与根因分析
适用场景
- 01选择有用的遥测属性
- 02理解基于事件的可观测性
- 03组织事故调查
- 04识别埋点缺口
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/observability-fundamentals确认已加载。
附带文件references/events-vs-metrics-vs-logs.md
详细介绍
可观测性基础
Honeycomb 可观测性方法背后的第一性原理。可用它为建议提供依据并回答概念性问题；有关 SDK 设置和特定工具的指导，请参阅 otel-instrumentation 和 query-patterns 技能。
定义
可观测性：通过检查系统产生的数据，理解并解释系统可能进入的任何状态的能力，无论状态多么新颖或复杂，而且无需针对每个新问题部署新代码。
宽事件：捕获一个工作单元完整上下文的扁平键值记录，包括请求发起者、端点、缓存命中/未命中、构建版本、耗时、错误状态，以及与操作相关的任何业务上下文。在 OpenTelemetry 中，span 就是一个宽事件。
高基数：一个字段可能拥有的唯一值数量。包含数百万个值的 user.id 属于高基数。只有少数几个值的 http.method 属于低基数。
高维度：事件中不同字段的数量。包含 50 个属性的 span 具有高维度。
| 概念 | 可观测性 | 传统监控 |
|---|---|---|
| 问题 | 任意，事先未知 | 预先定义（仪表板、警报） |
| 数据形态 | 在查询时决定 | 在埋点时决定 |
| 基数 | 高基数很有价值 | 高基数成本高 |
| 调查 | 探索 → 缩小范围 → 确认 | 查看仪表板 → 升级处理 |
为什么使用宽事件
你收集的数据形态会限制之后可以提出的问题。指标会在埋点时预先聚合并丢弃上下文。宽事件则保留上下文，让你在查询时决定分析的形态。
span 上的每个属性都是可查询的维度。在同一个 span 中添加 user.id、deployment.version 和 cache.hit，即可在单个查询中将它们关联起来——“较慢的请求来自租户 X，使用版本 2.3.1，且缓存未命中。”单独的指标无法做到这一点，因为每种维度组合都会创建一个新的时间序列。
Honeycomb 的存储引擎可以处理高基数和高维度，而不会像指标系统那样导致成本激增。添加 user.id 这类高基数字段不会创建数百万个时间序列——它只是每个事件上的另一个列，在查询时进行聚合。
事件与指标、日志的对比
| 结构化事件（Spans） | 指标 | 日志 | |
|---|---|---|---|
| 捕获内容 | 完整的请求上下文（所有属性） | 带低基数标签的预聚合数值 | 每行的文本或结构化字段 |
| 丢弃内容 | 不丢弃任何内容——保留原始事件 | 单个请求、高基数维度 | 行与行之间的关联（没有跟踪上下文时） |
| 查询能力 | 可对任意维度执行 GROUP BY、筛选、BubbleUp | 对预定义维度进行快速聚合 | 文本搜索、结构化字段查询 |
| 成本变化 | 随事件量线性增长 | 随维度数量（基数）呈指数增长 | 随数据量线性增长，查询成本不一 |
| 最适用于 | 调查、根因分析 | 低成本警报、长期趋势 | 审计跟踪、罕见事件 |
同样的埋点工作，既可以生成指标或日志行，也可以生成宽事件；而事件能提供这三种能力：计数（指标）、读取（日志）、跨维度分析（可观测性）。
如需查看同一操作采用三种方式进行埋点的代码示例，请参阅
${CLAUDE_PLUGIN_ROOT}/skills/observability-fundamentals/references/events-vs-metrics-vs-logs.md。
核心分析循环
在 Honeycomb 中调试遵循一个循环：定义 → 可视化 → 调查 → 评估。
- 定义 — 明确问题。从告警、SLO 预算消耗或用户报告入手。
- 可视化 — 运行查询，查看问题的形态（HEATMAP、COUNT、P99）。
- 调查 — 使用 BubbleUp（自动比较所有维度上的异常值与基线）和追踪分析缩小范围。
- 评估 — 通过查询有无疑似原因的情况，验证假设。
然后继续循环——每个答案都会引出新的问题。BubbleUp 会比较每一列中的分布，自动完成第 2-3 步，但前提是事件包含足够多可供比较的维度。
如需了解如何使用 Honeycomb 工具实现这一循环的结构化工作流，请参阅 production-investigation 技能。
检测如何与调查相连
Span 上的每个属性都是一个维度，BubbleUp 可用它来查找根本原因。事件期间最重要的属性可回答三个问题：
- 谁受到影响？ — 用户、租户、账户层级、区域
- 发生了什么变化？ — 部署版本、功能标志、配置版本
- 瓶颈在哪里？ — 业务操作 Span、耗时细分、缓存状态
检测应围绕你凌晨 3 点会提出的问题进行，而非追求面面俱到。如果调查期间 BubbleUp 没有返回有用结果，通常是检测存在缺口——添加缺失的维度并重试。
完整的属性目录请参阅
${CLAUDE_PLUGIN_ROOT}/skills/otel-instrumentation/references/wide-event-attributes.md。
有关添加属性的 SDK 指南，请参阅 otel-instrumentation 技能。
将检测作为开发实践
检测并非一次性设置任务。编写代码的工程师最了解哪些操作至关重要、哪些路径容易出错，以及哪些上下文有助于调试。应像对待测试一样对待检测：规划功能时规划遥测，在代码审查中检查遥测，并将补充缺失维度作为事件后续跟进工作。
其他资源
参考文件
${CLAUDE_PLUGIN_ROOT}/skills/observability-fundamentals/references/events-vs-metrics-vs-logs.md— 代码示例：将同一操作表示为事件、指标和日志
交叉引用
- 有关 SDK 设置和自定义检测：otel-instrumentation 技能
- 有关实现核心分析循环的调查工作流：production-investigation 技能
- 有关自主分析检测缺口：instrumentation-advisor Agent