PostHog 自有代码接入 Metrics 产品全指南从 SDK 埋点到 OTel 回退的第一方指标管线【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog导读本文围绕 PostHog 仓库中 instrumenting-first-party-metrics 技能文档展开讲解如何让 PostHog 自有的 Pythonweb/Celery/Temporal与 Node 代码把应用指标以与外部客户完全相同的方式送入PostHog Metrics 产品posthog.metrics表与 Metrics UI。读完本文你将掌握按运行环境选择SDK 优先、OTel 回退的埋点路径、各 SDK 的版本门槛posthog-python 7.23.0 / posthog-node 5.43.0 / posthog-js ~1.399.0、仓库内已就绪的配置与 flush 钩子、counter/gauge/histogram 的标准写法以及如何验证指标真正到达。背景与目标把 PostHog 自己的指标送进自己的 Metrics 产品PostHog 的 Metrics 产品面向所有客户允许通过各语言 SDK 上报 counter、gauge 与 histogram 三类指标。本技能文档的目标很明确PostHog 自身仓库中的代码web 进程、Celery worker、Temporal worker、nodejs/服务也要用同一条管道埋点让内部指标落在posthog.metrics表中、出现在 Metrics UI 里而不是另起炉灶发明一套私有方案。核心原则有三条原文强调埋点前必须牢记尽可能跟随公开文档走 SDK 路径只有当当前环境的 SDK 版本或运行时无法走 SDK 时才用 OTel 作为回退。不要发明环境变量不要手搓 OTel provider——仓库里每个环境都已经有一条可用的路径。Metrics 产品与 Prometheus/Grafana 是互补的两套观测体系本文描述的是推送到posthog.metrics的路径Grafana 侧基于被抓取的prometheus_client埋点依然存在并继续工作详见 celery.py 中关于PROMETHEUS_MULTIPROC_DIR与端口 8001 的注释。Step 1识别运行环境选定埋点路径第一步是确定代码运行在哪里然后据此选择首选方案与回退方案。文档给出了一张环境决策表运行位置首选方案回退方案Monorepo Pythonweb、Celery、TemporalSDKposthoganalytics.default_client.metrics——前提是锁定的版本已支持见版本门槛OtelInstrumentFactoryposthog/otel_metrics.pyMonorepo Node 服务nodejs/——这些服务并不运行 posthog-node内部孪生实现nodejs/src/common/metrics/otel-metrics.tsPostHog 自有的独立服务 / 脚本 / 其他仓库按公开文档用 SDKposthog.metrics.count/gauge/histogram按文档配置 OTLP 环境变量OTEL_EXPORTER_OTLP_METRICS_ENDPOINThost/i/v1/metricsBearer 项目 token⚠️ 关键警告Temporal worker 里 OTel 回退等于沉默原文用一个醒目的警告块指出一个非常容易被踩的坑在 Temporal worker 中OTel 回退并不是回退而是静默。OTEL_METRICS_EXPORT_URL/_TOKEN只配置在 web 部署上没有配置在 worker 部署上因此OtelInstrumentFactory在那里绑定的是一个 no-op meter所有 twin 都被丢弃。也就是说从 worker activity 里通过 factory 记录的指标从来没有到达过 Metrics 产品而同一批 pod 上走 SDK 路径的指标却可以。从 worker 出发请走 SDK 路径或使用 Temporal 自己的 metric meter。同时不要指望prometheus_client那一半 twin 能弥补被丢弃的另一半。仓库里create_worker默认会启动CombinedMetricsServerenable_combined_metrics_serverTrue由TEMPORAL_COMBINED_METRICS_SERVER_ENABLED控制该服务器在 worker 的 metrics 端口上同时提供 Python registry 与 Temporal SDK 自身的指标。因此registry 默认会被导出但只有当 combined server 仍被启用、且部署层面确实去抓取该端点时它才会到达 Grafana——这两者都属于仓库之外的部署配置在你把prometheus_client埋点当作 worker 的唯一出口之前必须先确认它们。Step 2检查版本门槛不要假设posthog.metrics在各 SDK 中的首发版本posthog-python 7.23.0posthoganalytics是同一包改名而来posthog-node 5.43.0posthog-js ~1.399.0运行时检查typeof posthog.metrics?.count function在 monorepo 中验证方式在 pyproject.toml 里grep posthoganalytics并与 7.23.0 对比。以当前仓库为准锁定版本为posthoganalytics7.47.1已高于门槛SDK 路径从 web 与 Celery 直接可用。若你的分支低于门槛则先走 OTel 回退直到依赖 bump 落地。值得注意的是monorepo 是bump-ready的posthog/apps.py 已设置模块级的 metrics 配置service_name/service_version/environment在 pre-7.23 的版本上这些属性会被忽略一旦posthoganalytics7.23被固定SDK 路径无需任何应用层改动即可生效Celery 的worker_process_shutdown钩子posthog/celery.py负责 flush 最后一个指标窗口同样在旧版本上保持惰性。apps.py中的配置原文如下它保证了指标与同一进程的 trace 共享服务身份fallback 与 posthog/otel_instrumentation.py 的 trace resource 一致posthoganalytics.metrics { # Same fallback as the OTel trace resource — metrics and traces from one # process must share a service identity. service_name: settings.OTEL_SERVICE_NAME or posthog-django-default, service_version: os.getenv(COMMIT_SHA), environment: os.getenv(OTEL_SERVICE_ENVIRONMENT), }仓库之外对照上述版本检查 lockfile/requirements升级依赖而不是绕开它。Step 3埋点保持与公开文档一致的形态SDK 路径与公开文档完全一致client.metrics.count(invoices.processed, 1, attributes{plan: pro}) client.metrics.gauge(queue.depth, 42) client.metrics.histogram(job.duration, 187, unitms)要点monorepobump 之后中客户端是posthoganalytics.default_client配置与 flush 钩子都已就绪直接记录即可短生命周期进程与回收型 worker 必须显式 flushclient.metrics.flush()——monorepo 的 Celery 钩子已经做了这件事。看 posthog/celery.pyclient.metrics在内存中聚合、按间隔 flush回收的子进程--max-tasks-per-child若不 flush 会丢掉最多一个间隔的样本flush 被限定在 5 秒超时内、运行在 daemon 线程里且对未配置/被禁用的客户端保持惰性设置 service namemonorepo 已从OTEL_SERVICE_NAME配置好fallback 为posthog/posthog-django-default——Metrics UI 就是靠它过滤的。仓库里一个真实的 SDK 路径调用站点是 products/managed_warehouse/backend/metrics.py从 Temporal worker 走 SDK 路径。它非常值得学习因为展示了三个实战细节Replay 抑制_should_record()通过temporalio.workflow.in_workflow() and workflow.unsafe.is_replaying()判断是否处于 workflow 重放中重放时不记录避免重放事件产生虚假指标同时把 temporalio 的导入放在函数内部避免把 Temporal SDK 拖进django.setup()的导入路径防御性取客户端_metrics()从posthoganalytics.default_client取client.metrics客户端为None时直接返回不记录完整的三类型示例track_duckling_backfill上下文管理器同时记录 started/finished 两个 counter、一个 last-success 时间戳 gauge、一个 duration histogram并在finally里metrics.flush()显式冲刷——这就是短生命周期路径手动 flush的模板。Monorepo 中的 OTel 回退OtelInstrumentFactory调用方零配置from posthog.otel_metrics import OtelInstrumentFactory _otel OtelInstrumentFactory(myarea) _otel.counter(myarea.jobs.processed).add(1, {outcome: success}) _otel.histogram(myarea.job.duration, units).record(1.87, {queue: default}) _otel.gauge(myarea.backlog).set(42)从源码看posthog/otel_metrics.py 的实现揭示了若干关键原理惰性、按 PID 的 provider 生命周期_ensure_provider()用进程 PID 作为缓存键gunicorn/Celery 这类 prefork 服务器中每个 worker 子进程都会各自构建带 exporter 线程的活 provider而不是继承父进程死掉的 providerprovider 重建会递增内部_epochfactory 据此丢弃绑定到旧 provider 的 instrument 缓存零配置安全降级只有当OTEL_METRICS_EXPORT_URL与OTEL_METRICS_EXPORT_TOKEN同时设置时才真正构建 provider否则返回NoOpMeter——未配置是安全的 no-op而不是错误配置内部推送细节exporter 指向capture-logs服务的/i/v1/metrics用Bearer项目 token 认证且必须走internal_requests_session()绕过 Smokescreen 出口代理否则每个批次都会静默 407resource 标识service.name取OTEL_SERVICE_NAMEfallbackposthog-python、service.version取COMMIT_SHA、service.instance.id为hostname-PID——后者至关重要没有它所有 worker 进程共享同一条序列交错的累积 counter 会被读成持续重置rate()/increase()会按进程数严重高估twin 机制record_counter_twin/record_histogram_twin/record_gauge_twin/timed_histogram_twin从已有的prometheus_clientinstrument 派生名字、描述与 bucket 边界让两个 sink 不会漂移。例如 counter 会补回prometheus_client内部剥离的_total后缀histogram 会继承 prom 的 bucket 阶梯去掉最后的Inf。twin 全部吞掉异常因为它们在热路径与错误处理器里运行遥测抛错会掩盖真正的故障。官方推荐最小的参考调用站点是 products/dashboards/backend/access.py它定义了posthog_dashboard_access_total、posthog_dashboard_cache_outcome_total两个 prom 计数器并在record_dashboard_access与record_dashboard_cache_outcome中分别用record_counter_twin同步写入 OTLP 孪生指标。Node 侧内部孪生otel-metrics.tsnodejs/服务不运行 posthog-node所以回退方案是内部孪生 nodejs/src/common/metrics/otel-metrics.ts。其逻辑与 Python 侧一致同样要求OTEL_METRICS_EXPORT_URL与OTEL_METRICS_EXPORT_TOKEN同时设置通过createOtlpMeterProvider建立推送到capture-logs /v1/metrics的 providerserviceName默认node-${PLUGIN_SERVER_MODE ?? nodejs}并注册 shutdown 钩子。recordPiiReplacements展示了与 Python 侧同样的惰性获取 instrument模式OTel API 没有代理 provider模块加载时就创建 counter 会永远绑定在 noop meter 上因此 counter 在首次记录时才创建resetPiiReplacementsCounterForTests是测试接缝。两条路径共同遵守的规则点号分隔的稳定命名jobs.processed而不是metric1histogram 必须显式指定unit只使用低基数属性route、status、plan——绝不能用 user/session/request IDteam_id要克制且有目的地使用。Step 4验证指标真的到达先弄清落点。monorepo 里 SDK 路径落到 dogfood US 项目token 在 posthog/apps.py 中配置内部 OTel 路径落到 charts 中OTEL_METRICS_EXPORT_TOKEN指向的项目。两者可能不同——建 dashboard 前务必确认。Dev/test 陷阱。monorepo 的 DEBUG 与 TEST 环境下默认客户端是disabled的SDK 路径本地什么都不记录这是设计使然本地OTEL_METRICS_EXPORT_URL/_TOKEN未设置OTel factory 同样 no-op。要真实打通管道用带显式Posthog(token, host, metrics{service_name: yourname-scratch})客户端的草稿脚本打到一个真实项目bin/verify-metrics-pipe只能检查本地 collector 管道本身而且只上报 ingestion 服务自身的指标logs-ingestion/metrics-ingestion/nodejs永远不会包含你从 Python 发出的指标——检查你自己指标的到达情况要用下面的方法。观察到达约 1 分钟摄入延迟。三种途径任选MCPmetric-names-list搜索你的指标名然后query-metricscounter 用increasegauge 用avghistogram 用histogram_quantileMetrics UI 的指标名选择器SQLSELECT * FROM posthog.metrics WHERE metric_name ... ORDER BY timestamp DESC LIMIT 10。单元测试。posthog/test/test_otel_metrics.py 是官方模板test_unconfigured_is_a_safe_noop验证未配置时 factory 返回的是NoOpMeter记录动作完全安全test_configured_records_through_the_sdk_pipeline用override_settings注入 URL/token、mockOTLPMetricExporter捕获导出数据断言 counter/histogram/gauge 与两个 twin 指标都出现在导出结果中且 twin histogram 的explicit_bounds精确继承 prom bucket[0.5, 1, 5]test_timed_histogram_twin_observes_prom_and_propagates_exceptions验证计时 twin 在 body 抛异常时仍会观察 prom histogram、异常照常传播。测试里始终使用reset_otel_metrics_for_tests()override_settings来操控 gatingSDK 路径则 mock 客户端或断言client.metrics._series状态——测试里绝不发真实网络请求。什么不要做不要新增环境变量。OTEL_METRICS_EXPORT_URL/_TOKEN内部推送是 charts 层级的部署配置OTEL_EXPORTER_OTLP_METRICS_*只属于外部应用。未设置意味着安全的 no-op不是配置错误。不要自己构建MeterProvider/exporter 或缓存 OTel instrument——posthog/otel_metrics.py 已经拥有惰性、fork 安全、按 PID 的 provider 生命周期重复造轮子反而会引入死 provider 或重复 instrument 告警。版本门槛不过时不要手搓 workaround——正解是依赖 bump接线已提前落地或者暂时用 OTel factory 过渡。相邻但不属于本技能范围Grafana 体系通过被抓取的prometheus_client埋点端口 8001 常开以及一次性批任务用的pushed_metrics_registry/PushGatewayTaskPROM_PUSHGATEWAY_ADDRESS都继续存在并正常工作——本技能只管 Metrics 产品。只有当现有 Grafana dashboard 依赖某个 prom 指标时才需要保留该 prom instrument 并配上 twin。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
