⚡

Honeycomb观测分析Skill honeycomb-analysis

Honeycomb 观测性分析技能，用于通过脚本和查询语法对 Honeycomb 平台的数据集、跟踪和指标进行高基数探索，帮助快速识别错误模式、性能瓶颈和进行故障排除。关键词：Honeycomb, 观测性分析, 高基数, 数据查询, 脚本工具, DevOps, 故障排除。

DevOps 0 次安装 0 次浏览 更新于 3/15/2026

名称: honeycomb-analysis 描述: Honeycomb 观测性分析。用于查询 Honeycomb 数据集、跟踪或指标。提供脚本和查询语法参考，用于高基数探索。 允许的工具: Bash(python *)

Honeycomb 分析

认证

重要: 凭证由代理层自动注入。不要检查环境变量中的 HONEYCOMB_API_KEY — 它不会对您可见。直接运行脚本；认证是透明处理的。

您可以检查的配置环境变量（非机密）：

  • HONEYCOMB_API_ENDPOINT — Honeycomb API 端点（默认：https://api.honeycomb.io）

强制：统计优先调查

永远不要转储原始事件。 始终遵循此模式：

统计 → 样本 → 模式 → 关联
  1. 统计优先 — 在采样前了解数量、错误率和顶部模式
  2. 战略采样 — 基于统计选择正确的策略
  3. 模式提取 — 聚类相似错误以找到根本原因
  4. 上下文关联 — 在异常时间戳周围进行调查

可用脚本

所有脚本位于 .claude/skills/observability-honeycomb/scripts/

主要调查脚本

get_statistics.py — 始终从此开始

综合性统计，附带模式提取。

python .claude/skills/observability-honeycomb/scripts/get_statistics.py 数据集 [--time-range 秒] [--filter 过滤器]

# 示例：
python .claude/skills/observability-honeycomb/scripts/get_statistics.py production --time-range 3600
python .claude/skills/observability-honeycomb/scripts/get_statistics.py api-requests --filter "http.status_code >= 500"

输出包括：

  • 总事件数
  • 按状态码的错误分布
  • 顶部服务/端点
  • 顶部错误模式（用于快速分类的关键）
  • 可操作建议

run_query.py — 自定义查询

运行带有聚合的自定义分析查询。

python .claude/skills/observability-honeycomb/scripts/run_query.py 数据集 --calc 计算 [--breakdown 字段] [--filter 过滤器]

# 计算：COUNT, SUM, AVG, MAX, MIN, P50, P75, P90, P95, P99, HEATMAP, COUNT_DISTINCT
# 示例：
python .claude/skills/observability-honeycomb/scripts/run_query.py production --calc COUNT
python .claude/skills/observability-honeycomb/scripts/run_query.py production --calc P99 --column duration_ms --breakdown service.name
python .claude/skills/observability-honeycomb/scripts/run_query.py production --calc COUNT --filter "http.status_code >= 500" --breakdown error.message

list_datasets.py — 数据集发现

列出环境中的可用数据集。

python .claude/skills/observability-honeycomb/scripts/list_datasets.py

# 输出：数据集列表，带有名称和最后写入时间

Honeycomb 查询概念

计算（聚合）

计算 描述 示例
COUNT 计数事件 总请求数
SUM 对列求和 总传输字节数
AVG 平均值 平均持续时间
MAX / MIN 极值 峰值延迟
P50, P75, P90, P95, P99 百分位数 P99 延迟
HEATMAP 分布 延迟热图
COUNT_DISTINCT 唯一值 唯一用户数
RATE_AVG, RATE_SUM, RATE_MAX 每秒率 请求数/秒

过滤器

过滤器使用运算符来缩小结果范围：

列 = 值          # 精确匹配
列 != 值         # 不相等
列 > 值          # 大于
列 >= 值         # 大于或等于
列 < 值          # 小于
列 <= 值         # 小于或等于
列 存在           # 字段存在
列 不存在         # 字段缺失
列 包含 "字符串"   # 包含子字符串
列 以 "前缀" 开头  # 以前缀开头
列 在 (a, b, c) 中 # 在集合中

分解（分组）

分解按字段值拆分结果：

# 按服务分组
--breakdown service.name

# 多个分解
--breakdown service.name --breakdown http.method

常见字段

Honeycomb 通常有以下字段（根据仪器不同而变化）：

# 跟踪字段
跟踪.跟踪标识
跟踪.跨度标识
跟踪.父标识
持续时间_毫秒
名称

# HTTP 字段
http.方法
http.网址
http.状态码
http.主机

# 服务字段
服务.名称
服务.版本

# 错误字段
错误
错误.消息
异常.类型
异常.消息

调查工作流

标准事件调查

┌─────────────────────────────────────────────────────────────┐
│ 1. 统计优先（强制）                              │
│    python get_statistics.py <数据集>                        │
│    → 了解数量、错误率、顶部模式                   │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
                     高错误率？
               ┌─────────────┴─────────────┐
               │                           │
       是 (>5%)                           否
               │                           │
               ▼                           ▼
┌─────────────────────────────┐  ┌───────────────────────────────────────────┐
│ 2. 快速路径                │  │ 2. 定向调查                 │
│    直接查询错误    │  │    按特定标准过滤            │
│    python run_query.py      │  │    python run_query.py 数据集            │
│    --filter "error=true"    │  │    --filter "duration_ms > 1000"          │
│    --breakdown error.message│  │    → 查找异常                   │
└─────────────────────────────┘  └───────────────────────────────────────────┘

快速命令参考

目标 命令
开始调查 get_statistics.py <数据集>
计数错误 run_query.py <数据集> --calc COUNT --filter "error=true"
按服务的 P99 延迟 run_query.py <数据集> --calc P99 --column duration_ms --breakdown service.name
错误分布 run_query.py <数据集> --calc COUNT --filter "error=true" --breakdown error.message
列出数据集 list_datasets.py

SLOs 和触发器

检查 SLOs

python .claude/skills/observability-honeycomb/scripts/run_query.py <数据集> --list-slos

检查触发器（警报）

python .claude/skills/observability-honeycomb/scripts/run_query.py <数据集> --list-triggers

避免的反模式

  1. 永远不要跳过统计 — get_statistics.py 是强制的第一步
  2. 无界查询 — 始终指定时间范围（默认：1 小时）
  3. 获取所有事件 — 使用聚合，而不是原始事件转储
  4. 忽略错误率 — 高错误率意味着立即调查
  5. 缺少服务过滤器 — 对于多服务数据集，始终按服务过滤

与其他平台的关键区别

  • 原生高基数 — Honeycomb 擅长处理高基数字段（用户 ID、请求 ID）
  • 无预聚合 — 查询运行在原始事件上，支持临时探索
  • 跟踪优先 — 为分布式跟踪设计，而不仅仅是日志
  • BubbleUp — 使用分解自动识别异常维度