PostHog Signals Scout：observability gaps 可观测性缺口扫描器全解析

PostHog Signals Scoutobservability gaps 可观测性缺口扫描器全解析【免费下载链接】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/posthogPostHog Signals 中的signals-scout-observability-gaps是一个专注于可观测性缺口的自动化侦察 Agentscout它持续对比团队正在产生的事件与团队已经建立的观测手段洞察、看板、告警在缺口越过阈值时直接向 inbox 撰写推荐报告。本文基于仓库中该 scout 的完整技能定义SKILL.md并结合报告通道合约report-contract.md、去重与记忆约定dedupe-and-memory.md以及项目画像构建源码builders.py系统讲解它的设计哲学、六类缺口探查方法、报告决策流程与底层实现机制。读完你可以完整理解这类推荐型侦察 Agent 的判别逻辑并掌握如何在 PostHog 中阅读与维护它产出的报告。Scout 的角色定位推荐而非告警observability gaps scout 与其他专业 scout错误追踪、告警、异常检测等在形态上有一个本质区别它的产出是推荐recommendations而不是问题problems。它发现的是事件产出与观测覆盖之间的结构性差距并在差距达标后推荐新的洞察insight、看板dashboard增量或告警alert配置。正因为是推荐它的门槛更高一个嘈杂的你应该追踪 X的推荐流会摧毁 inbox 的信噪比。因此该 scout 的核心理念是宁可少而精不可多而噪。推荐一些团队已经有了的东西或为噪声事件推荐覆盖比什么都不推荐更糟。这一点也决定了它的运行姿态空跑是真实且有价值的产出。它直接通过报告通道scout-emit-report/scout-edit-report撰写报告一条推荐从研究到成稿 1:1 端到端负责而不是发出弱信号等待流水线聚合。如果 inbox 已有推荐、只是证据volume、reach发生了变化那是一次edit而非新报告。技能文件的 frontmatter 定义了它的运行边界来自 SKILL.mdname: signals-scout-observability-gaps scout-display-name: Observability gaps compatibility: PostHog Signals agent (Claude sandbox). Read-only analytics signal_scout_internal:write (scratchpad) signal_scout_report:write (report channel), plus the analytics and entity tools in the MCP tools section (read-data-schema, query-trends, query-paths, execute-sql over system.* tables, event-definitions-list, alerts-list, dashboards-get-all). allowed_tools: - emit_report - edit_report metadata: owner_team: signals scope: observability_gaps快速关闭Quick close-out两条低成本的退出路径路径一团队太小无缺口可查如果项目画像中的top_events为 null或少于约 5 个事件以 100/天以上的频率触发这个项目就太安静了缺口分析无法产生真正的推荐。关键陷阱windowed 而非 lifetime。每个top_events行都携带window_days字段计数是滚动窗口统计而非全生命周期统计。一个近期采集capture中断的项目与一个从未有流量的项目读起来完全一样。因此在基于稀薄下结论前必须先排除采集缺口如果计数对于一个看起来活跃的团队已配置集成、有已保存洞察、近期有活动可疑地偏薄应直接用execute-sql在更长窗口如 30 天上确认而不是轻信画像快照——临时性缺口是另一个 surface 的采集问题而非真实的量能缺失。只有当低量能在更宽窗口内持续成立时才写入一条 scratchpad 记录并空跑收尾keynot-applicable:observability_gaps:team{team_id}content简要说明checked at {timestamp}, top_events count 5 above 100/day, too quiet for gap analysis后续的 observability-gaps 运行会冷读这条记录并在几秒内短路退出。用相同 key 重跑会幂等地刷新时间戳——该记录会一直保留直到团队成长出有意义的量能届时下一次运行会重写或删除它。路径二团队已饱和成熟项目数千个洞察、数百条告警会在几次运行后确认整族缺口已饱和每个高量事件都有密集覆盖新涌现的事件几天内就会被覆盖。此时应将其记录为持久记忆而不是每次运行都重新发现keypattern:observability_gaps:family-saturated或跨家族的单一coverage-saturated记录content探测了什么、发现的覆盖计数以及一个触发线tripwire——家族值得重新探测的具体条件例如一个全新的广达事件类7 天内 ~1 万去重用户、零覆盖、属于离散的业务/功能指标而非环境遥测。一旦饱和被记录默认运行形态就变了对照最新画像检查触发线然后最多跑一次全新探测——一个此前任何运行都没覆盖的角度——以此赢得收尾而非继承收尾。如果触发线未触发且探测结果干净几分钟内即可空跑收尾。不要重跑几小时前刚验证过的覆盖 SQL——那是重复劳动不是尽职。一个必须内化的不对称性覆盖类家族1、3、4、5、6在成熟团队上是永久饱和的——每个高量事件都已有密集覆盖——但洞察漂移家族 2不会饱和。漂移随产品重命名和停用事件而持续产生因此在一个其他方面已饱和的团队上它是唯一持续多产的角度。应以它为先并把覆盖类家族视为继承饱和除非它们的触发线被触发。当存在多个探测角度新事件涌现、告警覆盖、洞察漂移时要轮换rotate每次运行挑选最久未被触碰的角度并继承其他角度的近期读数。轮换让每个 tick 都产生真正新鲜的收尾而不必每小时重跑相同的 SQL。一次运行的完整工作流运行在以下动作间循环跳过无用的回访有用的。定向Get oriented四次低成本冷启动读取scout-scratchpad-searchtextgap或textobservability——来自既往 observability 运行的持久团队导航。带有pattern:、noise:、addressed:、dedupe:、watch:、report:、reviewer:key 前缀的记录告诉你什么是常态、什么已浮现、什么该跳过、哪些缺口被暂存、哪份报告覆盖了哪条推荐、谁拥有这个 surface。这里至关重要因为同一个缺口绝不能被跨运行重复报告。scout-runs-list最近 14 天——既往 observability-gap scout 发现了什么、排除了什么。先浏览摘要只有当摘要提到你正在考虑的推荐时才拉取scout-runs-retrieve。scout-project-profile-get——top_events提供量能与触达popular_insights提供已保存的洞察recent_dashboards提供在用的看板existing_inbox_reports提供 inbox 中已有的报告。这一次读取就能告诉你检测缺口所需的大部分信息。从源码看builders.py该画像由build_inventory()聚合生成写入SignalProjectProfile.payloadjsonb 列其中_top_events()对events表执行 HogQL 查询按 7 天回看窗口TOP_EVENTS_LOOKBACK_DAYS 7统计 count、uniq(person_id)触达、最近 24h 计数/触达与窗口内首末次出现时间最多 50 个事件查询超时上限 20 秒TOP_EVENTS_MAX_EXECUTION_S失败时返回None以区别于团队无采集[]。inbox-reports-listordering-updated_atsearch具体事件/洞察/看板名——inbox 中已有的报告。注意你自己通过报告通道产出的报告其 backing signal 记录在source_productsignals_scout不是observability_gaps所以不要按 product 过滤——否则会漏掉你撰写过的每一份报告。之前已经提过的推荐是edit而非新报告撰写前先用inbox-reports-retrieve拉取最接近的匹配项。探查Explore六类值得关注的缺口家族以下六类家族按典型信号密度排序。没有一个是自动成立的——每一条都需要经过量能 覆盖检查 去重三重验证才能成为发现。家族 1高量自定义事件无洞察覆盖自定义事件非$pageview/$identify这类$builtin每天以有意义的量触发但没有任何已保存洞察引用它。直接调用read-data-schema events——获取事件名 24h 量能。针对system.insights执行execute-sql——查找在name、description或queryJSON 中提到该事件名的洞察。模式query::text ILIKE %{event_name}%。检查event-definitions-list的last_seen_at新近度和verified标志——团队是否已将其标记为值得追踪。强信号事件 1000/天、无洞察引用、verifiedtrue。弱信号事件 100/天、未类型化、零星触发。量能排名的盲区一个刚诞生、触达广但人均频率低的事件可能永远排不进按 count 排序的top_events而 7 天查询窗口会截断min(timestamp)无法区分新旧事件。因此要用宽窗口直接探测涌现events 表、最近 60 天、event NOT LIKE $%、按事件分组只保留min(timestamp) now() - 14d真正的新事件且最近 7 天去重用户超过触达下限~500的组按触达排序。每个命中都是 top-events 镜头结构性看不见的候选者对它运行与其他候选者相同的覆盖检查和排除项。家族 2洞察漂移——已保存洞察指向零量事件已有洞察过滤事件 X但 X 在过去 7 天触发次数为 0或接近 0。通常是以下原因事件被重命名如signed_up→sign_up_completed洞察未更新。事件被停用产品变更弃用洞察已过期。上游采集损坏这是另一个镜头——让 error-tracking scout 负责。直接调用对system.insights执行execute-sql抽取每个洞察过滤的事件序列。用query-trends测量这些事件的近期量能。对零量事件搜索event-definitions-list中名称相似的事件Levenshtein 相近、相同前缀、相同属性形状提示可能的重命名。强信号洞察仍活着近期last_modified_at或通过system.dashboard_tiles钉在活跃看板上且其主事件 7 天内 0 触发且名称相似的事件 100/天。注意system.insights暴露last_modified_at但没有last_viewed_at列——活着只能通过修改新近度或活跃看板 tile 来证明不能用查看新近度。家族 3关键事件无告警配置有些事件自报家门——payment_failed、signup_failed、*_error、*_blocked。只要它们有触发且没有告警就是缺口。使用项目自身的模式在事件词汇表中搜索failed、error、blocked、denied、rejected、timeout、crashed等词。直接调用按名称模式failed、error等过滤read-data-schema events。alerts-list——现有告警及其目标。query-trends确认量能非平凡不是一次性偶发。强信号事件名暗示失败语义、触发 10/天、零告警覆盖。弱信号名称含error但实为良性开发者遥测。家族 4看板范围缺口某个主题已存在看板名称 描述匹配OnboardingRevenueConversion等领域但与该主题相关的高量事件不在看板的任何洞察上。直接调用dashboards-get-all——现有看板 标签 描述。对每个看板通过 dashboard tile 端点或system.insights WHERE id IN (dashboard.insight_ids)列出洞察。通过名称重叠将领域主题事件与看板匹配。强信号看板明确以领域命名、 5 个事件匹配该领域且各自 1000/天、但全部不在看板上。弱信号任意关键词重叠。家族 5漏斗候选——有序序列事件模式无漏斗洞察三个或更多事件在用户会话中频繁以固定顺序共现且没有漏斗洞察追踪该序列。通常是 onboarding 流程、注册流程、结账流程等。直接调用query-paths一次调用探查热门去重事件浮现常见序列。对system.insights WHERE filters::text ILIKE %FunnelsQuery%执行execute-sql查找现有漏斗。检查序列长度与留存各步骤完成用户百分比。强信号3 步序列、 1000 用户完成第 1 步、 50% 到达第 2 步、无现有漏斗覆盖该序列。此处的门槛很高因为漏斗是主观的——常见序列不一定是有效漏斗。家族 6属性基数 / 缺失的 breakdown高量事件上有高基数属性而现有追踪该事件的洞察都不使用 breakdown——团队正在因聚合而丢失维度。直接调用read-data-schema event_property_values——查看某属性的去重取值。对该事件执行system.insights上的execute-sql——抽取breakdownFilter形状。比较属性基数与是否有洞察按它 breakdown。强信号属性有 5–50 个去重取值非无界、事件 5000/天、无洞察按它 breakdown。弱信号属性有 1000 去重取值会撑爆图表或 ≤ 2 个取值不增加信息。决策Decideauthor 还是 edit 一份报告这里的发现是推荐一个行动而非暴露一个问题。通用的报告机制——先搜索 inbox通过report:observability_gaps:gap指针或对缺口的_具体_实体做inbox-reports-list搜索而非gap这样的宽泛词、edit-vs-author、状态规则、评审者路由、非幂等去重、priority/repository/actionability 字段——都位于 harness prompt 和 report-contract.md 中不需要在此重新推导。本 scout 只在其上叠加 observability-gaps 的专属判断。每份报告的必需元素具体的事件/洞察/看板——实体 ID 进入证据列表让人类可以一键直达。量能 触达数字——缺口之所以重要是因为N个事件影响了M个用户两者都要引用。建议行动——在事件 X 上创建 trends 洞察/更新洞察 Y 指向事件 Z/把洞察 A 加到看板 B/为事件 C 配置告警。具体优于抽象。为什么是现在——如果这个缺口已存在数周为什么现在浮现因为量能刚跨过阈值因为新事件类涌现量能 新近度是去重键。门槛的权衡bar量能阈值——缺口只有在规模上才结构性地有趣。低于 100/天推荐就是噪声。稳定而非偶发Stable-not-spurious——缺口必须在项目时区中持续存在至少7 个完整天。避免标记昨天刚出现的事件部分当前天或部署日峰值可能伪装成稳定。无既有覆盖——author 前搜索popular_insights和existing_inbox_reports。如果之前某次运行已推荐过该缺口选择 edit 或跳过。然后对每个跨过门槛的候选者Edit当一份仍然活跃的报告已推荐该缺口、且其证据只是数字移动了量能进一步攀升、触达扩大时——用append_evidence追加新数字而不是铸造一份近乎重复的报告。Author 全新报告仅当没有任何活跃报告覆盖该缺口时。推荐是调查而非代码修复因此actionabilityrequires_human_inputrepositoryNO_REPO。优先级几乎总是P3一条建议关键失败语义事件家族 3——payment_failed、*_error、*_blocked在零告警覆盖下触发时是P2。Remember / Park通过下面的 watch 生命周期暂存低于门槛的候选者。Skip如果noise:/addressed:/dedupe:记录或现有 inbox 报告已覆盖它写一行说明跳过。兄弟协作礼貌上游采集损坏事件停止触发属于 error-tracking scout已配置但触发未命中的告警属于 insight-alerts scout被查看洞察自身的异常属于 anomaly-detection scout。你独特的角度永远是结构性的覆盖缺口而不是其之上的异常。暂存再 authorwatch 生命周期大多数好推荐不是在发现的当次运行就被提交的——它们被暂存直到稳定性门槛跨过。生命周期如下Park暂存——写入watch:observability_gaps:gap记录携带判别条件使这成为真实缺口的确切检查、迄今的量能证据以及最早提交时间第 7 个完整项目时区天结束时。未来运行继承该候选者而不是重新推导。Re-verify live, then author现场复核后再 author——跨过门槛的那次运行必须在 author 前对每条判别条件用实时数据重新检查覆盖可能已出现、量能可能已崩坍。绝不能仅凭 watch 记录提交。Guard守卫——author 后用report_id和约 30 天的去重期更新 watch 记录除非出现实质性新角度否则在此之前不重复报告。写入report:observability_gaps:gap指针让下次运行 edit 而非重复并在reviewer:observability_gaps:area下缓存已解析的负责人。Retire退役——记录不会永远存在。当覆盖出现推荐已被执行时删除记录或转为addressed:。若约 30 天过去仍无人建立覆盖说明已推荐但被忽略——转为noise:跳过记录而不是重复报告。收尾Close out总结本次运行——一段话你看了什么、author/edited 了哪些报告、记住了什么、排除了什么及原因。harness 将总结写入运行行作为可搜索的散文未来运行通过scout-runs-list读取它。不要单独写运行元数据scratchpad 记录——运行总结已承担该角色。排除项Disqualifiers这些必须跳过无已保存洞察的内置事件——$pageview、$autocapture、$identify、$set、$opt_in、$groupidentify、$feature_flag_called通过 PostHog 产品视图Web Analytics、Feature Flags即可呈现无需自定义洞察。不要推荐创建。内部用户的测试事件——为已知内部 distinct_ids 钉一条noise:observability_gaps:internal-distinct-ids记录并在量能统计中跳过它们。已禁用 feature flag 的事件——若事件仅在 flag 禁用或极低 rollout 百分比时触发量能是人为偏低的。临时一次性看板上的事件——只有一个查看者的私有看板不算已覆盖。使用popular_insights的查看者数阈值。环境型 app-shell 遥测——去重用户触达约等于$pageview的事件意味着它几乎为每个用户随 app shell 触发而非离散的功能指标。其上零已保存洞察通常是刻意的称其为缺口前先与$pageview对比触达。刻意的工程 firehose——团队通过临时 SQL 或 notebook 消费的高量内部性能/遥测事件。宣布零覆盖前检查 notebook 是否引用该事件——按选择覆盖不是缺口。实验曝光事件——用于驱动实验指标的事件由实验本身覆盖。实验运行期间不要为它们推荐独立洞察。每人一次的生命周期事件——onboarding、wizard、setup 事件每人触发一次它们的量能只是注册流程的流转很少值得独立洞察。限时促销/营销活动事件——活动形态的事件按设计出现、飙升、结束。归于沉寂不是漂移缺乏覆盖不是缺口除非底层 surfaceimpressions conversions持续存在。事件调查脚手架——事件期间创建的短期事件通常附带事件命名的洞察。事件关闭后它们停止触发把停止标记为漂移是误报。一次性回填/部署峰值——新埋点事件可能在单次采集倾泻全部历史伪装成高触达的稳定指标。信任量能前按小时分桶toStartOfHour如果几乎所有事件_和_去重用户都落在同一小时内那是回填而非稳定指标——直接排除无论原始触达多少它都跨不过 7 完整天门槛。遗留事件名变体——故意将新旧事件名 union 起来保持历史连续性的洞察是维护良好的而非漂移。宣布死亡事件仍被引用前先读洞察的 query JSON。有疑问时写 scratchpad 记录而不是提交报告。推荐对任何观测 surface 的负责人都有很高的恐慌半径——误报会迅速侵蚀信任。MCP 工具全览直接调用只读read-data-schema——kindevents取量能kindevent_properties/event_property_values取基数与 breakdown。query-trends——确认证据中引用的近期窗口量能 触达数字。query-paths——漏斗候选的序列检测。insights-list——分页洞察目录慎用SQL 更快。dashboards-get-all——活跃看板 标签。event-definitions-list——事件定义元数据verified标志、last_seen_at、created_at、自定义-vs-内置标记。alerts-list——现有告警配置及其目标事件。对system.insights/system.dashboards/system.cohorts执行execute-sql——是否有洞察引用事件 X这类查询的快速路径。Inbox 与评审者路由机制见 report-contract.mdinbox-reports-list/inbox-reports-retrieve——inbox 中已有的报告author 前先检查以便 edit 而非重复ordering-updated_at。inbox-report-artefacts-list——可比报告的 artefact 日志评审者先例。scout-members-list——用于将suggested_reviewers路由到拥有该洞察/看板/产品 surface 的成员的运行内名册。Harness 级scout-project-profile-get——冷启动定向快照。已内置top_events、popular_insights[13]、recent_dashboards、existing_inbox_reports。其工具定义tools.yaml说明响应开头有紧凑的summary信封承载emit_eligibility决定产出能否到达 inbox 的门附一行remediation与 inbox 报告计数完整payload.inventory可长达数十 KB所以要从summary读门而非payload深处。scout-scratchpad-search/scout-scratchpad-remember/scout-scratchpad-forget——持久导航。从 scratchpad.py 的源码看检索是对content和key的 ILIKE 匹配key 最长为 300 字符MAX_SCRATCHPAD_KEY_LENGTHcontent 上限 5 万字符MAX_SCRATCHPAD_CONTENT_LENGTHremember以(team, key)幂等 upsertexpires_at是可选 TTL——过期记录退出搜索每日 janitor 在过期两周后硬删除。scout-runs-list/scout-runs-retrieve——既往运行发现了什么。scout-emit-report/scout-edit-report——撰写推荐报告/编辑现有报告报告通道合约在 harness prompt 中。如需更深的调查 playbooksandbox 镜像内置了上游 PostHog 技能posthog:querying-posthog-dataHogQL 语法 system.* 搜索模式和posthog:exploring-autocapture-events自定义事件与 autocapture 的区别及各自适用场景。报告通道与记忆机制的底层支撑author vs edit 的决策表报告通道合约report-contract.md给出了清晰的决策表你拥有…使用一份完整、成形、无现有报告覆盖的发现——以对 title/summary 的完全控制 1:1 提交emit_report关于已存在报告你自己上次运行撰写的或流水线报告的新信息edit_report一个尚不足以成为独立报告的观察都不——写 scratchpad 记录并继续调查状态由安全 × 可行动性决定安全判定actionability结果状态出现在 inboxsafeimmediately_actionableREADY是saferequires_human_inputPENDING_INPUT是safenot_actionableSUPPRESSED否unsafe任意SUPPRESSED否observability-gaps 的推荐是调查而非代码修复因此默认走requires_human_input路径PENDING_INPUT出现在 inbox 供人类采纳并配合NO_REPO与 P3 优先级家族 3 的失败语义事件零告警覆盖时升为 P2。去重与记忆的 key 前缀词汇表记忆约定dedupe-and-memory.md规定 scratchpad 无标签类别编码在 key 前缀中格式为prefix:domain:entity。observability-gaps 使用的核心前缀包括前缀用途pattern:团队数据常态的持久观察基线watch:仍在追踪但低于报告门槛的活跃问题要复查什么、跨过门槛的条件noise:要忽略的模式单用户、仅开发、无修复路径的复发addressed:团队确认的修复已上线或团队已不再关注的话题dedupe:在特定问题/指纹上闸住未来运行避免重复提交report:本 scout 撰写的报告——存report_id供下次运行 edit/去重reviewer:已解析的负责人裸小写 GitHub login供下次运行直接设置suggested_reviewersnot-applicable:产品/surface 在团队未使用的收尾备忘好的记录是面向未来运行可行动的带日期、命名实体 ID、给出明确条件仍在触发 → 升级安静 → 跳过、以精确时间锚点限定key 前缀使其可被找到。报告撰写的关键约束节选evidence上限 50 条每条{description, source_id}超限在判定/持久化前即验证失败。实体必须以 markdown 链接引用复用工具返回的_posthogUrl或用generate-app-url构建而非裸 IDtitle与 summary 首行保持纯文本inbox 会将其提升为卡片标题。actionability_explanation一句话论证可行动性判定already_addressed默认false。报告被写入时即使被SUPPRESSED也会返回report_id以便后续 edit 或去重。同类推荐不要重复提交emit_report有幂等键覆盖传输重试但跨运行去重是双向的、由 scout 自己负责——author 前inbox-reports-list查先例author 后写report:domain:entity记录。流水线可能日后重提升并重研究你的报告、覆盖你撰写的 title/summary——这是被接受的行为不要假设你的措辞不可变持久的我提交过凭证是report:scratchpad 记录与report_id而非标题文本。何时停止When to stopscratchpad 近期运行 画像显示你考虑过的每个领域都已有覆盖或已被推荐 → 空跑收尾。候选者匹配addressed:推荐已执行或noise:已推荐但被忽略前缀的 scratchpad 记录或现有 inbox 报告 → 一行说明后 edit-or-skip。你已验证 1–2 个高质量缺口并为其提交了报告 → 收尾即使还有可看的。质量优先于数量——推荐是预算不是目标。看了但没找到有意义的东西是真实产出不是失败。每一条没有发出去的推荐都是少一个侵蚀 inbox 的误报。相关资源技能本体products/signals/skills/signals-scout-observability-gaps/SKILL.md报告通道合约products/signals/skills/authoring-scouts/references/report-contract.md去重与记忆约定products/signals/skills/authoring-scouts/references/dedupe-and-memory.md项目画像构建源码products/signals/backend/scout_harness/profile/builders.py记忆工具实现products/signals/backend/scout_harness/tools/scratchpad.pyMCP 工具定义products/signals/mcp/tools.yamlSignals 架构总览products/signals/ARCHITECTURE.md【免费下载链接】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），仅供参考