用途:面向 PostHog 集成故障的快速应急响应。第一步始终是判断问题出在 PostHog 侧还是自身集成侧,可参考 PostHog Cloud 状态页 status.posthog.com。
严重级别:P1 分析完全中断(<15 分钟响应,如所有 capture 调用失败、功能开关返回默认值);P2 分析降级(<1 小时,如高延迟、部分事件丢失、开关评估慢);P3 轻微影响(<4 小时,如 webhook 延迟、特定事件类型缺失);P4 无用户影响(次日处理,如监控缺口、仪表盘数据陈旧)。
快速分诊:依次检查 PostHog Cloud 健康状态、事件采集、功能开关评估、管理 API 与自身健康端点。示例命令:curl -sf -o /dev/null -w "%{http_code}" https://us.i.posthog.com/healthz;采集测试使用 POST https://us.i.posthog.com/capture/;开关评估使用 POST https://us.i.posthog.com/decide/?v=3;管理 API 使用 https://app.posthog.com/api/projects/ 并带 Authorization: Bearer $POSTHOG_PERSONAL_API_KEY。
决策树:若 PostHog Cloud 不健康,则启用优雅降级、监控状态页,并注意采集为 fire-and-forget,故障期间事件会丢失;若健康,则按 401(API key 问题)、429(限流)、事件不出现(flush/shutdown)、开关返回默认值(personalApiKey)分别排查。
即时处置:401/403 校验项目 key 与个人 key 前缀并测试,必要时在 PostHog 仪表盘轮换并更新密钥;429 需缓存响应、降低轮询频率(私有 API 限流:分析端点 240/分钟、1200/小时,HogQL 1200/小时,本地开关轮询 600/分钟,采集端点无限制);事件不出现常见原因是 serverless 未调用 flush/shutdown,并需确认 API host 正确(采集端点为 https://us.i.posthog.com,而非 UI 的 https://app.posthog.com);开关返回默认值需添加 personalApiKey 并用 posthog.onFeatureFlags 等待加载。
优雅降级:用 try/catch 包裹 capture 与开关评估,失败时吞掉错误或返回安全默认值,确保 PostHog 故障不会导致应用崩溃。
事后证据收集:创建带时间戳的目录,保存 timeline、healthz 响应、脱敏后的 PostHog 环境变量、posthog-js/posthog-node 版本,并打包为 tar.gz。
限制:资料未提供具体价格、平台支持范围或效果保证;命令中的域名、密钥变量与端点需按实际环境替换。