instrument-metrics

添加 PostHog 指标采集

使用此技能为新代码或变更后的代码添加 PostHog 指标采集（计数器、仪表盘和直方图）。在实现功能或审查 PR 后使用此技能，确保关键操作都经过度量；也可在用户要求添加指标或计数器，或将现有指标埋点同步到 PostHog 时使用。支持任何平台或语言。

支持的平台：Web（JavaScript）、Node.js、通过 posthog.metrics SDK API 的 Python、通过 metrics agent 的 Kubernetes，以及通过 OpenTelemetry（OTLP）支持的任何语言。

说明

按顺序执行以下步骤：

步骤 1：分析代码库并检测平台。

• 检测语言、框架和现有指标配置。
• 查找依赖文件和项目文件（package.json、requirements.txt、pyproject.toml、go.mod、pom.xml 等）。
• 查找现有指标埋点：Prometheus 客户端（prom-client、prometheus_client）、StatsD/Datadog 客户端、OpenTelemetry meter 或 OpenTelemetry Collector 配置。
• 检查是否已安装 PostHog SDK（posthog-js、posthog-node、posthog-python）。

步骤 2：选择采集路径。

• 如果已安装 PostHog SDK（或平台支持该 SDK），请使用 posthog.metrics API——无需 OpenTelemetry 软件包。现在阅读对应平台的参考资料。
• 如果代码库已导出 OpenTelemetry 指标，请将现有 OTLP 指标导出器（或 Collector）指向 PostHog——阅读“其他语言”参考资料。除导出器配置外，无需更改应用代码。
• 如果以上两种情况都不适用，请使用“其他语言”参考资料作为备用方案——其中介绍了通用的 OpenTelemetry 方法。

步骤 3：与现有指标埋点并行添加。

• 如果代码库已记录某项指标（Prometheus 计数器、StatsD 调用或 OTel 仪表），请在现有埋点旁添加 PostHog 调用，并沿用相同的指标名称和属性。不要删除或重构现有埋点。
• 不要更改现有文件的基本架构。只进行少量、有针对性的添加。
• 尝试写入文件前，必须立即先读取该文件。

步骤 4：在合适的位置添加新指标。

• 如果用户要求添加新指标，或关键操作尚未覆盖，请在相应位置添加 PostHog 指标调用：统计关键流程的成功和失败次数，用直方图记录外部调用和作业耗时，用仪表记录队列深度和连接池大小。
• 选择正确的类型：只增不减的值用计数器；会上下波动的值用仪表；表示分布的数据（如耗时）用直方图。为直方图设置明确的单位（ms、bytes）。
• 选用稳定、描述性强、以点分隔的名称（jobs.processed、api.request.duration），并设置服务名称，以便轻松区分各个系统。

步骤 5：控制基数。

• route、status、plan 或 queue 等属性是合适的；用户 ID、会话 ID、请求 ID 和时间戳则不合适。每种唯一的属性组合都会创建一个新序列。
• 如果需要用户或请求级别的详细信息，应使用 PostHog 日志或追踪，而不是指标。 步骤 6：设置环境变量。（如果已配置 PostHog SDK，可跳过此步骤——posthog.metrics 会复用 SDK 现有的项目令牌。）
• 检查项目是否已配置 PostHog 环境变量（例如在 .env、.env.local 或特定框架的环境变量文件中）。如果已有有效值，则跳过此步骤。
• 如果缺少 PostHog 项目令牌，请使用 PostHog MCP 服务的 projects-get 工具获取项目的 api_token。如果返回了多个项目，请询问用户要使用哪个项目。如果 MCP 服务未连接或未经身份验证，请改为向用户索取其 PostHog 项目令牌。
• 对于 PostHog 主机 URL：检查 projects-get MCP 响应中的 region 字段——US 对应 https://us.i.posthog.com，EU 对应 https://eu.i.posthog.com。如果 MCP 响应或现有项目配置中没有区域信息，请询问用户：“您使用的是 PostHog US Cloud 还是 EU Cloud？”不要默认使用 US Cloud。
• 对于 OTLP 指标端点，根据上面确定的区域使用 https://us.i.posthog.com/i/v1/metrics（US）或 https://eu.i.posthog.com/i/v1/metrics（EU），并将项目令牌作为 Authorization: Bearer 标头传入。
• 按照框架的命名约定，将这些值写入相应的环境变量文件。
• 在代码中引用这些环境变量，不要硬编码它们。

步骤 7：验证指标是否送达。

• 对于生命周期较短的进程（脚本、cron 作业、无服务器函数），请在退出前刷新数据（posthog.metrics.flush()，或 OTel 提供程序的 forceFlush()/shutdown()）。
• 打开 PostHog 侧边栏中的 Metrics，然后在名称选择器中选择相应指标；发送后应在一分钟内看到数据点。

参考文件

• references/javascript.md - JavaScript（Web）指标安装
• references/nodejs.md - Node.js 指标安装
• references/python.md - Python 指标安装
• references/kubernetes.md - Kubernetes 指标安装
• references/other.md - 其他语言的指标安装
• references/start-here.md - 指标入门
• references/basics.md - 为什么需要指标
• references/architecture.md - 指标的工作原理
• references/COMMANDMENTS.md - 集成必须遵循的特定框架规则

每个平台参考文件都包含特定的 SDK 设置、OTLP 配置和集成模式。请找到与用户技术栈匹配的文件。

核心原则

• 环境变量：始终使用环境变量保存 PostHog 密钥和 OpenTelemetry 端点。切勿将它们硬编码。
• 尽量减少改动：在现有指标旁添加 PostHog 指标采集。不要替换或重构现有的检测代码。
• 优先使用 SDK：如果已安装 PostHog SDK，posthog.metrics 无需新软件包，也无需额外身份验证。仅对已采用 OpenTelemetry 的代码库或不支持 SDK 的语言配置 OTLP。
• 低基数：每种唯一的属性组合都会创建一个新序列。仅添加路由、状态或套餐等取值范围有限的维度，切勿添加用户 ID、会话 ID 或请求 ID。