PostHog 产品告警架构解析共享状态机、目的地注册表与调度计算的层职责边界【免费下载链接】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 仓库内的共享告警架构参考文档 architecture.md系统讲解 PostHog 告警平台的分层职责、生命周期状态机契约、目的地destination注册表、HogFunction 事件投递的确认机制以及纯 Python 调度数学的实现细节。读完本篇你将知道在 PostHog 中为某个产品新增或扩展告警能力时每一段代码应当落在哪一层、各层之间通过哪些纯函数契约交互以及错误处理语义failed/inconclusive/transient为何被设计为承重墙。分层地图先决定代码属于哪一层再动手共享告警架构文档开宗明义在编辑代码之前先用这张层表决定代码归属。该层表是整个文档的核心骨架它把告警系统拆成六层每一层都有明确的所有权边界层位置职责纯生命周期决策state_machine.py状态迁移、策略决策、通知动作共享告警基础设施products/alerts/backend/调度数学、目的地配置与持久化、内部事件投递、邮件传输、insight 告警模型/API、insight 评估产品适配器products/name/backend/领域评估、模型快照、唯一 mutator、事件载荷、允许的目的地列表、到期查询、历史记录、编排共享告警创建 UIAlertWizard可复用的 HogFunction 目的地、触发器与配置流程共享产品告警 UIproducts/alerts/frontend/components/容器无关的编辑器布局、定义原语、高级选项、目的地编辑器、调度展示、评估曲线产品 UIproducts/name/frontend/或frontend/src/scenes/name/表单逻辑、API 调用、产品字段、归一化适配器、入口点、详情表、向导配置两个参考采纳者reference adopter承担示范职责products/logs是固定周期调度fixed-cadence、HogFunction 目的地、投递回滚、产品自持的 Temporal 编排、共享产品告警编辑器组件的参考实现Insight 告警则是日历锚点calendar anchor、周末跳过、邮件投递的参考实现。两者都把各自的产品状态适配到共享生命周期引擎上并且共同使用共享的静默时段quiet hours调度约束。需要注意的是每个产品保留自己的模型、到期查询和调度持久化评估包evaluation package在 insight 的多种查询类型之间共享但它并不是一个面向无关产品的通用评估器。生命周期契约一台纯 Python 状态机products/alerts/backend/state_machine.py 是整个共享告警平台的心脏。它的模块文档字符串说明了设计哲学借鉴 Prometheus/Alertmanager 的拆分——评估保持领域特定留在各产品生命周期决策集中于此契约就是进CheckInput、出AlertCheckOutcome。架构文档列出的六个契约要素与源码一一对应CheckInput归一化一次产品评估。源码中它是一个 frozen dataclassstate_machine.py#L103-L112只有四个字段threshold_breached、is_inconclusive数据未落定、无法得出判决、error_message、is_transient_error。AlertSnapshot只包含生命周期决策所需字段状态、冷却期、last_notified_at、snooze_until、consecutive_failures以及 N-of-M 滑动窗口参数evaluation_periods/datapoints_to_alarm与最近一次检查之前的违约标志元组见 state_machine.py#L115-L128。AlertPolicy表达采纳者之间刻意的差异。它的默认值就是现有行为不是一份臆测选项菜单。源码注释明确写道Every flag encodes a real, observed divergence between products — do not add a flag speculativelystate_machine.py#L53-L59。仓库中已定义了两套现成策略LOGS_ALERT_POLICY AlertPolicy()与BILLING_ALERT_POLICY后者开启了broken_is_terminalFalse、transient_errors_count_toward_brokenTrue、renotify_while_firingTrue等见 state_machine.py#L89-L100。evaluate_alert_check(...)与evaluate_alert_failure(...)返回AlertCheckOutcome不做任何持久化。控制面辅助函数apply_enable、apply_disable、apply_snooze、apply_threshold_change以及apply_unsnooze、apply_user_reset返回ControlPlaneOutcome。两种 outcome 共享new_state与consecutive_failures字段因此都能流过产品同一条apply_outcome通道。NotificationAction告诉产品该投递哪个事件取值为NONE / FIRE / RESOLVE / ERROR / BROKEN。产品在本地把模型转成快照然后通过唯一的产品apply_outcome函数应用 outcome。架构文档还要求当另一个产品采纳这套契约时要扩展安全规则 .semgrep/rules/security/alert-state-must-go-through-state-machine.yaml把该产品的后端也纳入状态写入必须经过状态机的静态检查。错误语义是承重墙架构文档特别强调错误行为不是边角细节而是load-bearing承重设计。对照 state_machine.py 的实现可以逐条印证失败的检查不清除已触发firing的告警——evaluate_alert_failure的注释引经据典CloudWatch 的INSUFFICIENT_DATA不会清除ALARMfiring 告警会穿过一次失败检查使恢复后的 episode 得以延续而不是重新触发state_machine.py#L297-L306。inconclusive 检查保持状态与失败计数不变且不发出任何通知state_machine.py#L212-L219。瞬态错误默认静默除非策略显式选择计入transient_errors_count_toward_broken。源码注释解释原因集群抖动这类瞬态错误会同时打中一大片告警若每次都通知就会向所有目的地广播噪音state_machine.py#L307-L317。错误通知通常只在首个失败边沿0 → 1发生用计数器而非状态判断这样 SNOOZED 自动过期不会误触发再次报错通知state_machine.py#L331-L336。投递失败不得消费本应重试的生命周期/失败计数边沿——这条落在产品适配器的回滚语义上见下文投递契约。失败计数器达到MAX_CONSECUTIVE_FAILURES 5时升级为BROKEN状态并发出BROKEN通知若策略设置了disable_when_brokenoutcome 中会带disableTrue适配器必须同步持久化enabledFalse。目的地契约一个注册表加六个门面函数面向产品的目的地设置能力统一从 products/alerts/backend/facade/api.py 导出架构文档列出的六个函数在源码中全部可查validate_destination_databuild_alert_destination_configcreate_alert_destination_hog_functionssoft_delete_alert_destinationssoft_delete_all_alert_destinationssend_alert_email它们的定义分别位于 facade/api.py导出面、destination_configs.py、destinations.py 与 email_notifications.py且facade/api.py的__all__中还包括DESTINATION_SPECS、DestinationType、list_alert_destination_groups、owned_alert_destinations_qs等配套符号。EventKindSpec 与 DESTINATION_SPECS 注册表EventKindSpec描述单一事件类型的目的地无关内容面向模板的载荷字段。共享构建器把它转换成 HogFunction 载荷转换规则由DESTINATION_SPECS提供——这是注册表本体每种目的地类型在这里拥有自己的模板 ID、必填字段、输入构建、回读read-back与读取脱敏read redaction逻辑# products/alerts/backend/destination_configs.py第 294 行附近 DESTINATION_SPECS: dict[DestinationType, DestinationSpec] { spec.type: spec for spec in (SlackDestination(), DiscordDestination(), WebhookDestination(), TeamsDestination()) } SPEC_BY_TEMPLATE_ID: dict[str, DestinationSpec] {spec.template_id: spec for spec in DESTINATION_SPECS.values()}架构文档由此得出两条实操结论新增目的地类型 在这里加一条注册项事件 ID、事件属性、文案、动作与允许哪些目的地由产品自己拥有。也就是说共享层支持某目的地不等于该产品自动可用该目的地——允许列表是产品侧的白名单。删除是 fail-closed 的架构文档给出两条硬约束都指向 destinations.py 的实现删除操作必须用team_id、alert_id和产品的允许事件 ID 三重重范围限定对应soft_delete_alert_destinations/soft_delete_all_alert_destinations的签名见 destinations.py#L260-L311create_alert_destination_hog_functions拒绝创建告警已拥有的任何目的地因此调用方必须在锁定告警行的事务内调用它否则并发写入会绕过防重见 destinations.py#L196。投递契约内部事件的确认制四步流程HogFunction 通知 worker 直接使用 products.alerts.backend.destinations 完成投递架构文档把流程固化为四步produce_alert_internal_event(...)返回ProduceResult或None定义于 destinations.py#L399flush_alert_internal_events(...)刷新共享 producer——批处理 worker 应当每产出一个批次就 flush 一次destinations.py#L430模块内还定义了ALERT_NOTIFICATION_FLUSH_TIMEOUT_SECONDS 10.0与投递失败的 Prometheus 计数器posthog_alert_internal_event_delivery_failures_totalalert_internal_event_delivered(...)在 flush 之后逐条检查 producer 是否确认了每个内部事件destinations.py#L441产品只对已确认的内部事件持久化依赖通知的生命周期变更。这里有一个极其重要的语义边界ack 只确认生产成功进入内部事件传输层并不确认下游 HogFunction 的执行更不确认最终到达 Slack、Discord、webhook 或 Microsoft Teams。这些 helper 负责记录与捕获 producer 失败回滚、重试时机、调度推进、检查历史语义则由产品拥有。以 logs 为参考内部事件未被确认时其处理方式是在下一个周期重新评估而不是消费掉本应重试的边沿。邮件调用则统一走门面的send_alert_email(...)email_notifications.py#L6。调用方必须自己决定收件人含授权校验、主题、模板、上下文、错误处理以及一个稳定的campaign_key——后者是必需的因为重试与去重行为依赖它。调度契约纯 Python 的调度数学products/alerts/backend/scheduling.py 是纯 Python 模块无 Django/模型导入时区以 IANA 名传入、静默时段以解析后的元组传入拥有全部可复用的调度数学。架构文档列出的能力与源码的对应关系compute_shard_offset_seconds(...)把一个 UUID 标识的告警确定性地分配到调度器 tick 上。实现上以alert_id.int % shard_count生成分片索引跨 pod 重启稳定进程内hash()则不稳定以默认 60 秒调度间隔、5 分钟周期为例告警会被均匀散布到偏移 [0, 60, 120, 180, 240] 秒的 5 个槽位上避免 cron 一次拉起整个集群scheduling.py#L27-L48。advance_next_check_at(...)从上一个调度点推进、跳过错过的间隔、对齐到以午夜为锚的周期网格、再叠加分片偏移。注释解释了为什么要对齐网格调度器 cron 每分钟触发一次若返回的next_check_at带有分钟以下偏移如 12:05:30cron 会空转一整个 tick 去等它scheduling.py#L51-L84。已漂移的告警会在下次运行时惰性自愈。CalendarInterval与to_calendar_interval(...)产品面向的区间契约镜像posthog.schema.AlertCalculationInterval的取值real_time/every_15_minutes/hourly/daily/weekly/monthly。next_calendar_check_time(...)计算固定周期或团队本地时区的日/周/月锚点且在 DST 切换时保持墙钟wall-clock行为。锚点约定写在注释里日检锚在明天凌晨 1 点、周检锚在下周一凌晨 3 点、月检锚在次月 1 号凌晨 4 点只替换小时、保留分/秒以维持创建时间带来的散布scheduling.py#L149-L194。本地化逻辑用 pytz 处理AmbiguousTimeError/NonExistentTimeError两类 DST 边界。validate_and_normalize_schedule_restriction(...)与parse_blocked_windows_tuples(...)校验产品载荷并产出纯的阻塞窗口契约。校验规则具体而严格最多MAX_BLOCKED_WINDOWS 5个窗口单个窗口半开区间至少 30 分钟时间格式只允许HH:MM跨天窗口会被展开为[start, 1440)与[0, end)两段再合并合并后若覆盖全天则直接拒绝Leave at least one time in the day when this alert can runscheduling.py#L338-L394。scan_next_unblocked_utc(...)、is_utc_datetime_blocked(...)、is_weekend(...)应用时区感知的约束而不导入任何 Django 模型。scan_next_unblocked_utc从给定 UTC 时刻起逐分钟前扫找到第一个不在阻塞窗口内的分钟且带MAX_UNBLOCK_STEPS 1440 * 1414 天的步数上限防止死循环超时返回None由调用方决定兜底insight 告警的策略是推后一天并记录日志scheduling.py#L423-L447。架构文档在此给出两条使用纪律计算分片时使用调度器的真实间隔若产品调度器间隔不同于共享默认值 60 秒应包装compute_shard_offset_seconds传入schedule_interval_seconds创建、更新、推进告警时必须使用同一个分片函数保持全链路分片一致。到期资格、调度持久化、重试与编排则留在产品侧因为模型字段、状态、snooze 行为与租户约束各不相同。前端契约展示基础设施不是产品注册表共享产品告警 UI 位于 products/alerts/frontend/components/。架构文档的定位很关键它是展示基础设施而不是前端产品注册表。文档列举的组件与源码目录一一对应AlertEditor、AlertEditorFormDetails、AlertEditorSection提供容器无关的表单外壳见 AlertEditor.tsxAlertDefinition*系列组件提供可组合的定义、调度、下次评估与时区展示AlertDefinition.tsx、AlertDefinitionFields.tsx、AlertDefinitionSection.tsx;AlertAdvancedOptions拥有共享的折叠与 enabled-count 行为AlertAdvancedOptions.tsxQuietHoursFields从归一化后的 restriction、cadence 与项目时区渲染静默时段输入QuietHoursFields.tsxAlertNotificationDestinationEditor渲染归一化后的已保存与待保存目的地AlertNotificationDestinationEditor.tsx含测试 AlertNotificationDestinationEditor.test.tsxAlertEvaluationHistoryChart渲染归一化的评估点与当前阈值AlertEvaluationHistoryChart.tsx。边界规则同样清晰产品拥有带 key 的 kea logic、API 调用、表单 schema、来源/过滤控件、支持的目的地类型、HogFunction 载荷、阈值转换、enabled-count 计算与历史表模态框、场景宽度、内嵌区块的 sizing 留在产品侧。AlertWizard依然是共享的 HogFunction 创建流程实现见 frontend/src/lib/components/Alerting/AlertWizard/AlertWizard.tsx配套 alertWizardLogic.ts。采纳者提供带 key 的alertWizardLogicprops支持的子模板 ID、WizardTrigger[]、WizardDestination[]以及可选的 URL 或预设行为。后端支持某目的地并不自动使它在向导中可选——与后端目的地契约的白名单原则前后呼应。文档同时要求在新增或扩展产品告警前端之前先阅读 frontend-alerting.md遵循 frontend/src/AGENTS.md使用生成的 API 类型对应生成物在 products/alerts/frontend/generated/并对网络提交做防双击保护。参考采纳者的落地路径把上述契约落到具体产品上仓库中有两个现成样板logs固定周期 HogFunction 投递 Temporal 编排产品侧适配器 products/logs/backend/alert_state_machine.py 演示了选策略 → 模型转快照 → 领域评估转CheckInput→ 调evaluate_alert_check→ 唯一apply_outcome落库的完整链路目的地薄层 products/logs/backend/alert_destinations.py 演示了如何为每个通知动作定义一个EventKindSpec、显式声明允许的DestinationType值、并走门面做校验/构建/创建/删除。insight 告警日历锚点 周末跳过 邮件模型与状态机在 products/alerts/backend/models/alert.py 与 products/alerts/backend/insight_alert_state_machine.py其决策用例由测试覆盖products/alerts/backend/test/test_state_machine.py、products/alerts/backend/test/test_insight_alert_state_machine.py、products/alerts/backend/test/test_scheduling.py、products/alerts/backend/test/test_grid_scheduling.py是验证生命周期与调度契约最直接的入口。结语把告警当作一个端到端系统回到架构文档的主旨在编辑之前先决定代码属于哪一层。共享层保持纯 Python 与无产品分支产品层拥有模型、到期查询、编排与历史前端在共享组件之上做归一化适配生命周期用一台状态机加AlertPolicy表达差异目的地用一个注册表加白名单收敛扩展点投递用生产—flush—确认—仅持久化已确认四步把生命周期与传输的失败语义解耦调度则全部下沉到可测试的纯函数。理解并遵守这些契约是向 PostHog 任何产品添加告警能力、或扩展共享告警平台的第一步。更多工程细节采纳清单、平台扩展、前端规范可继续参见同目录下的 adopting-platform-alerting.md、extending-platform-alerting.md、frontend-alerting.md 与总纲 SKILL.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），仅供参考 PostHog 产品告警架构解析：共享状态机、目的地注册表与调度计算的层职责边界
PostHog 产品告警架构解析共享状态机、目的地注册表与调度计算的层职责边界【免费下载链接】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 仓库内的共享告警架构参考文档 architecture.md系统讲解 PostHog 告警平台的分层职责、生命周期状态机契约、目的地destination注册表、HogFunction 事件投递的确认机制以及纯 Python 调度数学的实现细节。读完本篇你将知道在 PostHog 中为某个产品新增或扩展告警能力时每一段代码应当落在哪一层、各层之间通过哪些纯函数契约交互以及错误处理语义failed/inconclusive/transient为何被设计为承重墙。分层地图先决定代码属于哪一层再动手共享告警架构文档开宗明义在编辑代码之前先用这张层表决定代码归属。该层表是整个文档的核心骨架它把告警系统拆成六层每一层都有明确的所有权边界层位置职责纯生命周期决策state_machine.py状态迁移、策略决策、通知动作共享告警基础设施products/alerts/backend/调度数学、目的地配置与持久化、内部事件投递、邮件传输、insight 告警模型/API、insight 评估产品适配器products/name/backend/领域评估、模型快照、唯一 mutator、事件载荷、允许的目的地列表、到期查询、历史记录、编排共享告警创建 UIAlertWizard可复用的 HogFunction 目的地、触发器与配置流程共享产品告警 UIproducts/alerts/frontend/components/容器无关的编辑器布局、定义原语、高级选项、目的地编辑器、调度展示、评估曲线产品 UIproducts/name/frontend/或frontend/src/scenes/name/表单逻辑、API 调用、产品字段、归一化适配器、入口点、详情表、向导配置两个参考采纳者reference adopter承担示范职责products/logs是固定周期调度fixed-cadence、HogFunction 目的地、投递回滚、产品自持的 Temporal 编排、共享产品告警编辑器组件的参考实现Insight 告警则是日历锚点calendar anchor、周末跳过、邮件投递的参考实现。两者都把各自的产品状态适配到共享生命周期引擎上并且共同使用共享的静默时段quiet hours调度约束。需要注意的是每个产品保留自己的模型、到期查询和调度持久化评估包evaluation package在 insight 的多种查询类型之间共享但它并不是一个面向无关产品的通用评估器。生命周期契约一台纯 Python 状态机products/alerts/backend/state_machine.py 是整个共享告警平台的心脏。它的模块文档字符串说明了设计哲学借鉴 Prometheus/Alertmanager 的拆分——评估保持领域特定留在各产品生命周期决策集中于此契约就是进CheckInput、出AlertCheckOutcome。架构文档列出的六个契约要素与源码一一对应CheckInput归一化一次产品评估。源码中它是一个 frozen dataclassstate_machine.py#L103-L112只有四个字段threshold_breached、is_inconclusive数据未落定、无法得出判决、error_message、is_transient_error。AlertSnapshot只包含生命周期决策所需字段状态、冷却期、last_notified_at、snooze_until、consecutive_failures以及 N-of-M 滑动窗口参数evaluation_periods/datapoints_to_alarm与最近一次检查之前的违约标志元组见 state_machine.py#L115-L128。AlertPolicy表达采纳者之间刻意的差异。它的默认值就是现有行为不是一份臆测选项菜单。源码注释明确写道Every flag encodes a real, observed divergence between products — do not add a flag speculativelystate_machine.py#L53-L59。仓库中已定义了两套现成策略LOGS_ALERT_POLICY AlertPolicy()与BILLING_ALERT_POLICY后者开启了broken_is_terminalFalse、transient_errors_count_toward_brokenTrue、renotify_while_firingTrue等见 state_machine.py#L89-L100。evaluate_alert_check(...)与evaluate_alert_failure(...)返回AlertCheckOutcome不做任何持久化。控制面辅助函数apply_enable、apply_disable、apply_snooze、apply_threshold_change以及apply_unsnooze、apply_user_reset返回ControlPlaneOutcome。两种 outcome 共享new_state与consecutive_failures字段因此都能流过产品同一条apply_outcome通道。NotificationAction告诉产品该投递哪个事件取值为NONE / FIRE / RESOLVE / ERROR / BROKEN。产品在本地把模型转成快照然后通过唯一的产品apply_outcome函数应用 outcome。架构文档还要求当另一个产品采纳这套契约时要扩展安全规则 .semgrep/rules/security/alert-state-must-go-through-state-machine.yaml把该产品的后端也纳入状态写入必须经过状态机的静态检查。错误语义是承重墙架构文档特别强调错误行为不是边角细节而是load-bearing承重设计。对照 state_machine.py 的实现可以逐条印证失败的检查不清除已触发firing的告警——evaluate_alert_failure的注释引经据典CloudWatch 的INSUFFICIENT_DATA不会清除ALARMfiring 告警会穿过一次失败检查使恢复后的 episode 得以延续而不是重新触发state_machine.py#L297-L306。inconclusive 检查保持状态与失败计数不变且不发出任何通知state_machine.py#L212-L219。瞬态错误默认静默除非策略显式选择计入transient_errors_count_toward_broken。源码注释解释原因集群抖动这类瞬态错误会同时打中一大片告警若每次都通知就会向所有目的地广播噪音state_machine.py#L307-L317。错误通知通常只在首个失败边沿0 → 1发生用计数器而非状态判断这样 SNOOZED 自动过期不会误触发再次报错通知state_machine.py#L331-L336。投递失败不得消费本应重试的生命周期/失败计数边沿——这条落在产品适配器的回滚语义上见下文投递契约。失败计数器达到MAX_CONSECUTIVE_FAILURES 5时升级为BROKEN状态并发出BROKEN通知若策略设置了disable_when_brokenoutcome 中会带disableTrue适配器必须同步持久化enabledFalse。目的地契约一个注册表加六个门面函数面向产品的目的地设置能力统一从 products/alerts/backend/facade/api.py 导出架构文档列出的六个函数在源码中全部可查validate_destination_databuild_alert_destination_configcreate_alert_destination_hog_functionssoft_delete_alert_destinationssoft_delete_all_alert_destinationssend_alert_email它们的定义分别位于 facade/api.py导出面、destination_configs.py、destinations.py 与 email_notifications.py且facade/api.py的__all__中还包括DESTINATION_SPECS、DestinationType、list_alert_destination_groups、owned_alert_destinations_qs等配套符号。EventKindSpec 与 DESTINATION_SPECS 注册表EventKindSpec描述单一事件类型的目的地无关内容面向模板的载荷字段。共享构建器把它转换成 HogFunction 载荷转换规则由DESTINATION_SPECS提供——这是注册表本体每种目的地类型在这里拥有自己的模板 ID、必填字段、输入构建、回读read-back与读取脱敏read redaction逻辑# products/alerts/backend/destination_configs.py第 294 行附近 DESTINATION_SPECS: dict[DestinationType, DestinationSpec] { spec.type: spec for spec in (SlackDestination(), DiscordDestination(), WebhookDestination(), TeamsDestination()) } SPEC_BY_TEMPLATE_ID: dict[str, DestinationSpec] {spec.template_id: spec for spec in DESTINATION_SPECS.values()}架构文档由此得出两条实操结论新增目的地类型 在这里加一条注册项事件 ID、事件属性、文案、动作与允许哪些目的地由产品自己拥有。也就是说共享层支持某目的地不等于该产品自动可用该目的地——允许列表是产品侧的白名单。删除是 fail-closed 的架构文档给出两条硬约束都指向 destinations.py 的实现删除操作必须用team_id、alert_id和产品的允许事件 ID 三重重范围限定对应soft_delete_alert_destinations/soft_delete_all_alert_destinations的签名见 destinations.py#L260-L311create_alert_destination_hog_functions拒绝创建告警已拥有的任何目的地因此调用方必须在锁定告警行的事务内调用它否则并发写入会绕过防重见 destinations.py#L196。投递契约内部事件的确认制四步流程HogFunction 通知 worker 直接使用 products.alerts.backend.destinations 完成投递架构文档把流程固化为四步produce_alert_internal_event(...)返回ProduceResult或None定义于 destinations.py#L399flush_alert_internal_events(...)刷新共享 producer——批处理 worker 应当每产出一个批次就 flush 一次destinations.py#L430模块内还定义了ALERT_NOTIFICATION_FLUSH_TIMEOUT_SECONDS 10.0与投递失败的 Prometheus 计数器posthog_alert_internal_event_delivery_failures_totalalert_internal_event_delivered(...)在 flush 之后逐条检查 producer 是否确认了每个内部事件destinations.py#L441产品只对已确认的内部事件持久化依赖通知的生命周期变更。这里有一个极其重要的语义边界ack 只确认生产成功进入内部事件传输层并不确认下游 HogFunction 的执行更不确认最终到达 Slack、Discord、webhook 或 Microsoft Teams。这些 helper 负责记录与捕获 producer 失败回滚、重试时机、调度推进、检查历史语义则由产品拥有。以 logs 为参考内部事件未被确认时其处理方式是在下一个周期重新评估而不是消费掉本应重试的边沿。邮件调用则统一走门面的send_alert_email(...)email_notifications.py#L6。调用方必须自己决定收件人含授权校验、主题、模板、上下文、错误处理以及一个稳定的campaign_key——后者是必需的因为重试与去重行为依赖它。调度契约纯 Python 的调度数学products/alerts/backend/scheduling.py 是纯 Python 模块无 Django/模型导入时区以 IANA 名传入、静默时段以解析后的元组传入拥有全部可复用的调度数学。架构文档列出的能力与源码的对应关系compute_shard_offset_seconds(...)把一个 UUID 标识的告警确定性地分配到调度器 tick 上。实现上以alert_id.int % shard_count生成分片索引跨 pod 重启稳定进程内hash()则不稳定以默认 60 秒调度间隔、5 分钟周期为例告警会被均匀散布到偏移 [0, 60, 120, 180, 240] 秒的 5 个槽位上避免 cron 一次拉起整个集群scheduling.py#L27-L48。advance_next_check_at(...)从上一个调度点推进、跳过错过的间隔、对齐到以午夜为锚的周期网格、再叠加分片偏移。注释解释了为什么要对齐网格调度器 cron 每分钟触发一次若返回的next_check_at带有分钟以下偏移如 12:05:30cron 会空转一整个 tick 去等它scheduling.py#L51-L84。已漂移的告警会在下次运行时惰性自愈。CalendarInterval与to_calendar_interval(...)产品面向的区间契约镜像posthog.schema.AlertCalculationInterval的取值real_time/every_15_minutes/hourly/daily/weekly/monthly。next_calendar_check_time(...)计算固定周期或团队本地时区的日/周/月锚点且在 DST 切换时保持墙钟wall-clock行为。锚点约定写在注释里日检锚在明天凌晨 1 点、周检锚在下周一凌晨 3 点、月检锚在次月 1 号凌晨 4 点只替换小时、保留分/秒以维持创建时间带来的散布scheduling.py#L149-L194。本地化逻辑用 pytz 处理AmbiguousTimeError/NonExistentTimeError两类 DST 边界。validate_and_normalize_schedule_restriction(...)与parse_blocked_windows_tuples(...)校验产品载荷并产出纯的阻塞窗口契约。校验规则具体而严格最多MAX_BLOCKED_WINDOWS 5个窗口单个窗口半开区间至少 30 分钟时间格式只允许HH:MM跨天窗口会被展开为[start, 1440)与[0, end)两段再合并合并后若覆盖全天则直接拒绝Leave at least one time in the day when this alert can runscheduling.py#L338-L394。scan_next_unblocked_utc(...)、is_utc_datetime_blocked(...)、is_weekend(...)应用时区感知的约束而不导入任何 Django 模型。scan_next_unblocked_utc从给定 UTC 时刻起逐分钟前扫找到第一个不在阻塞窗口内的分钟且带MAX_UNBLOCK_STEPS 1440 * 1414 天的步数上限防止死循环超时返回None由调用方决定兜底insight 告警的策略是推后一天并记录日志scheduling.py#L423-L447。架构文档在此给出两条使用纪律计算分片时使用调度器的真实间隔若产品调度器间隔不同于共享默认值 60 秒应包装compute_shard_offset_seconds传入schedule_interval_seconds创建、更新、推进告警时必须使用同一个分片函数保持全链路分片一致。到期资格、调度持久化、重试与编排则留在产品侧因为模型字段、状态、snooze 行为与租户约束各不相同。前端契约展示基础设施不是产品注册表共享产品告警 UI 位于 products/alerts/frontend/components/。架构文档的定位很关键它是展示基础设施而不是前端产品注册表。文档列举的组件与源码目录一一对应AlertEditor、AlertEditorFormDetails、AlertEditorSection提供容器无关的表单外壳见 AlertEditor.tsxAlertDefinition*系列组件提供可组合的定义、调度、下次评估与时区展示AlertDefinition.tsx、AlertDefinitionFields.tsx、AlertDefinitionSection.tsx;AlertAdvancedOptions拥有共享的折叠与 enabled-count 行为AlertAdvancedOptions.tsxQuietHoursFields从归一化后的 restriction、cadence 与项目时区渲染静默时段输入QuietHoursFields.tsxAlertNotificationDestinationEditor渲染归一化后的已保存与待保存目的地AlertNotificationDestinationEditor.tsx含测试 AlertNotificationDestinationEditor.test.tsxAlertEvaluationHistoryChart渲染归一化的评估点与当前阈值AlertEvaluationHistoryChart.tsx。边界规则同样清晰产品拥有带 key 的 kea logic、API 调用、表单 schema、来源/过滤控件、支持的目的地类型、HogFunction 载荷、阈值转换、enabled-count 计算与历史表模态框、场景宽度、内嵌区块的 sizing 留在产品侧。AlertWizard依然是共享的 HogFunction 创建流程实现见 frontend/src/lib/components/Alerting/AlertWizard/AlertWizard.tsx配套 alertWizardLogic.ts。采纳者提供带 key 的alertWizardLogicprops支持的子模板 ID、WizardTrigger[]、WizardDestination[]以及可选的 URL 或预设行为。后端支持某目的地并不自动使它在向导中可选——与后端目的地契约的白名单原则前后呼应。文档同时要求在新增或扩展产品告警前端之前先阅读 frontend-alerting.md遵循 frontend/src/AGENTS.md使用生成的 API 类型对应生成物在 products/alerts/frontend/generated/并对网络提交做防双击保护。参考采纳者的落地路径把上述契约落到具体产品上仓库中有两个现成样板logs固定周期 HogFunction 投递 Temporal 编排产品侧适配器 products/logs/backend/alert_state_machine.py 演示了选策略 → 模型转快照 → 领域评估转CheckInput→ 调evaluate_alert_check→ 唯一apply_outcome落库的完整链路目的地薄层 products/logs/backend/alert_destinations.py 演示了如何为每个通知动作定义一个EventKindSpec、显式声明允许的DestinationType值、并走门面做校验/构建/创建/删除。insight 告警日历锚点 周末跳过 邮件模型与状态机在 products/alerts/backend/models/alert.py 与 products/alerts/backend/insight_alert_state_machine.py其决策用例由测试覆盖products/alerts/backend/test/test_state_machine.py、products/alerts/backend/test/test_insight_alert_state_machine.py、products/alerts/backend/test/test_scheduling.py、products/alerts/backend/test/test_grid_scheduling.py是验证生命周期与调度契约最直接的入口。结语把告警当作一个端到端系统回到架构文档的主旨在编辑之前先决定代码属于哪一层。共享层保持纯 Python 与无产品分支产品层拥有模型、到期查询、编排与历史前端在共享组件之上做归一化适配生命周期用一台状态机加AlertPolicy表达差异目的地用一个注册表加白名单收敛扩展点投递用生产—flush—确认—仅持久化已确认四步把生命周期与传输的失败语义解耦调度则全部下沉到可测试的纯函数。理解并遵守这些契约是向 PostHog 任何产品添加告警能力、或扩展共享告警平台的第一步。更多工程细节采纳清单、平台扩展、前端规范可继续参见同目录下的 adopting-platform-alerting.md、extending-platform-alerting.md、frontend-alerting.md 与总纲 SKILL.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），仅供参考