Sentry Workflow Engine 数据模型深度解析检测、条件、工作流与运行时状态【免费下载链接】sentryDeveloper-first error tracking and performance monitoring项目地址: https://gitcode.com/GitHub_Trending/sen/sentry导读本文基于 Sentry 开源仓库中 workflow_engine 数据模型文档 展开深入剖析新一代 Workflow Engine 的持久化图结构从DataSource到Detector的检测链路、条件与条件组的三种角色、Workflow及其动作连接再到DetectorState、WorkflowFireHistory等运行时状态表。读完本文你将掌握各模型之间的关联方式、所有权约束与不变量、生命周期与缓存失效规则以及项目迁移relocation与测试覆盖的实践要点可直接对照仓库源码继续深入。一、总体概念图Workflow Engine 的持久化图Workflow Engine 用一组相互关联的 Django 模型描述“检测 → 条件判断 → 工作流触发 → 动作执行”的完整链路。官方文档用一张 ER 图概括全貌概念图省略了兼容模型其核心关系包括组织Organization拥有数据源与工作流项目Project拥有检测器DetectorDataSourceDetector是数据源与检测器之间的多对多映射检测器拥有触发器条件组Detector.workflow_condition_group触发组内包含若干检测条件DetectorWorkflow连接检测器与工作流而工作流归组织所有工作流拥有 WHEN 条件组与WorkflowDataConditionGroupIF 组IF 组内包含 IF 条件并通过DataConditionGroupAction门控动作检测器维护DetectorState运行状态与DetectorGroup关联 Issue Platform GroupWorkflowActionGroupStatus与WorkflowFireHistory分别负责重复频率抑制与触发历史记录。缩略名与实际模型的对应关系ER 图中的缩略名是条件角色condition roles而非模型名这一点最容易造成混淆ER 图名称实际模型与挂载点WHEN_GROUP/WHEN_CONDITIONWorkflow.when_condition_group指向的DataConditionGroup/DataConditionIF_GROUP/IF_CONDITIONWorkflowDataConditionGroup.condition_group指向的条件组及其条件DETECTOR_TRIGGER_GROUPDetector.workflow_condition_group指向的条件组关于运行时控制流官方文档指引参见 Execution。二、检测图Detection Graph1.DataSource通用数据源引用DataSource归属于某个组织organization外键并以通用方式引用一个会产出检测器输入的产品模型。其关键设计(type, source_id)组合在数据库层面全局唯一见UniqueConstraint(fields[type, source_id], nameunique_type_source_id)组织不参与该唯一约束type在data_source_type_registry中注册选中的DataSourceTypeHandler提供通用引用无法表达的额外行为source_id使用文本类型因为被引用的源模型主键类型不统一如监控器、订阅、uptime 订阅调用方必须通过注册的 handler 来解析而不能自行假设它指向哪个模型。从源码看DataSource.__relocation_dependencies__显式声明了三种已知源类型依赖monitors.monitorcron 监控器、sentry.querysubscriptionSnuba 查询订阅、uptime.uptimesubscriptionuptime 订阅与文档所述“Snuba 查询订阅、uptime 订阅、cron 监控器”一致。数据库层为(organization, type, source_id)建立了复合索引以支持按源快速反查。2.DataSourceDetector源与检测器的多对多映射DataSourceDetector是数据源与检测器之间的查找表through model其约束(data_source, detector)唯一workflow_engine_uniq_datasource_detector。一个数据源可以喂给多个检测器一个检测器也可以按所属产品模型的规则连接多条源记录检测器按数据源查找是有缓存的因此任何变更都必须走 receiver 驱动的失效路径详见下文“生命周期与失效”。3.Detector检测的配置单元Detector是配置好的检测单元核心字段与关系如下字段 / 关系含义project普通检测器的所属项目可空用于组织级 issue-stream 检测器project__isnullTrue且typeIssueStreamGroupType.slug时通过config__organization_id定位组织见DetectorQuerySet.by_organizationtypeIssue PlatformGroupType的 slugworkflow_condition_group触发器条件组将输入映射到优先级等级字段可空且唯一config检测器类型专属设置通过DetectorSettings.config_schemaJSON Schema校验由JSONConfigBase提供校验能力enabled用户控制的启用/静默snooze状态db_defaultTruestatus生命周期状态包括待删除ObjectStatus.PENDING_DELETION、DELETION_IN_PROGRESS与套餐级禁用ObjectStatus.DISABLED检测器类型即GroupType注册表检测器类型在 Django app 之外注册具体的GroupType提供DetectorSettings定义于 types.py其中可定义运行时 handlerhandlerAPI 校验器validator配置 JSON schemaconfig_schema检测器可见性的查询过滤器detector_type_filters。文档明确警告不要再建第二个检测器注册表GroupType注册就是检测器类型的注册表。源码中Detector.detector_handler与Detector.settings属性正是通过grouptype.registry.get_by_slug(self.type)解析找不到时抛出ValueError。无唯一约束与并发创建Detector不强制(project, type)的数据库唯一约束。默认检测器的创建依赖短分布式锁 幂等查找见 defaults/detectors.py使用sentry.locksDetector.get_default_detector_for_project还借助缓存CACHE_TTL 600秒减少查询。Manager 的get_queryset默认排除待删除/删除中的记录。触发器条件组历史命名的字段检测器的workflow_condition_group指向一个DataConditionGroup该关系可空且唯一uniqueTrue, on_deletemodels.SET_NULL独立于 Workflow 侧的条件关系。文档提醒字段名是历史遗留——它虽然叫workflow_condition_group实际属于检测器求值与 Workflow 无关。4. 检测链路中的缓存键与快照缓存键get_detector_project_type_cache_key生成detector:by_proj_type:{project_id}:{detector_type}快照Detector.get_snapshot()返回{id, type, enabled, status, trigger_condition}DetectorSnapshot中trigger_condition是DataConditionGroupSnapshot条件读取Detector.get_conditions()优先复用已缓存的条件组否则用单条查询DataCondition.objects.filter(condition_group__detectorself)避免 N1。三、条件体系DataCondition与DataConditionGroup1.DataCondition单条逻辑条件DataCondition的字段如下字段含义type存储的条件类型Condition枚举如eq、gte、lt、every_event、issue_priority_equals等comparisonJSON 比较值/配置condition_result命中时返回的 JSON 结果condition_group必填的父条件组外键on_deleteCASCADE求值机制evaluate_value基础比较运算eq/gt/gte/lt/lte/ne走CONDITION_OPS映射到operator.eq/ge/gt/le/lt/ne直接求值其余类型通过condition_handler_registry找到DataConditionHandler执行handler.evaluate_value(value, comparison)布尔结果会转换为condition_result命中或None未命中结果类型约束为DataConditionResult DetectorPriorityLevel | int | float | bool | None非法值返回ConditionError求值被scopedstats.timer()与metrics.timer(workflow_engine.data_condition.evaluation_duration)观测慢条件事件频率类会被打上speed_categoryslow标签。Schema 校验enforce_data_condition_json_schema对非基础运算类型使用 handler 的comparison_json_schema校验comparison字段。2.DataConditionGroup逻辑组合DataConditionGroup拥有组织organization外键on_deleteCASCADE与存储的逻辑类型logic_typelogic_type语义any求值所有条件任一命中即为真any-short一旦有条件命中即短路停止all全部命中才为真none全部未命中才为真任一命中立即返回假条件组存在三种预期角色检测器触发器组Detector.workflow_condition_groupWorkflow 的 WHEN 组Workflow.when_condition_groupWorkflow 的 IF/动作过滤组WorkflowDataConditionGroup.condition_group。文档强调这些关系之间不强制角色互斥通用校验器也不校验 handler 的放置位置必须靠创建代码按约定保持角色分离。规范化的求值、校验与放置契约参见 Conditions。四、工作流图Workflow Graph1.DetectorWorkflow检测器 ↔ 工作流DetectorWorkflow是连接检测器与工作流的 join 模型(detector, workflow)唯一unique_together两端on_deleteCASCADE。它决定与某个检测器关联的 issue 事件哪些工作流是候选。一个 issue 事件可以按多个检测器维度查询候选工作流已知的具体检测器项目级的 issue-stream 检测器可选的、组织级 all-projects issue-stream 检测器。这样工作流既可以精准命中产品专属检测器也可以覆盖更广的 issue 流。2.Workflow组织作用域的工作流Workflow是组织作用域organization外键模型重要字段字段 / 关系含义when_condition_group可选的触发器组在动作过滤之前求值数据库层有唯一约束workflow_engine_workflow_when_condition_group_id_..._uniqenvironmentNULL表示所有环境或指向某一个具体环境config.frequency重复抑制间隔分钟JSON Schema 定义type: integer, minimum: 0DEFAULT_FREQUENCY 30enabled是否可运行db_defaultTrue即“snooze”工作流的手段status删除状态追踪Manager 排除待删除/删除中记录evaluate_trigger_conditions的语义很关键如果没有 WHEN 条件组工作流视为默认触发返回resultTrue, triggeredTrue若条件组在删除/迁移中丢失则记录异常并返回未触发 ConditionError。调用方可以批量预取条件组传入以避免 N1。get_slow_conditions用于收集 WHEN 组中的慢条件便于在处理器中区分快慢路径。3.WorkflowDataConditionGroup工作流 → IF 组WorkflowDataConditionGroup把一个工作流连接到一个 IF/动作过滤条件组condition_group字段uniqueTrue因此一个条件组通过该关系只能属于一个工作流。4.DataConditionGroupAction与Action动作的连接与执行DataConditionGroupAction把动作连接到 IF 组带cond_group_action_idx索引Action存储动作类型及 handler 专属配置。动作类型Action.Type包括slack、slack_staging、msteams、discord、pagerduty、opsgenie、github、github_enterprise、jira、jira_server、vsts、email、sentry_app、plugin、webhook其中除 email/sentry_app/plugin/webhook 外均为集成动作is_integration()返回 Truedata中对应集成 key动作类型通过action_handler_registry选择 handlerhandler 通常实现在所属的集成或通知包中而非workflow_engine内部一个动作可以被多个工作流可达数据模型不定义动作执行顺序Action.trigger()组装ActionInvocation(event_data, action, detector, notification_uuid, workflow_id)并调用handler.execute(invocation)全程有workflow_engine.action.trigger.execution_time计时与计数指标get_dedup_key()由type、integration_id、config剔除target_display与data组合出动作去重键。五、运行时状态与历史Runtime State and History1.DetectorState持久化的检测器状态DetectorState存储检测器与其可选DetectorGroupKey的持久化状态。detector_group_key让一个检测器可以为数据包中的多个值例如不同端点分别追踪独立状态。关键约束唯一约束detector_state_unique_group_key使用Coalesce(detector_group_key, Value())把 NULL 组键视为空值从而保证未分组检测器只有一行状态。状态跨存储拆分运行时契约的一部分PostgreSQL 持久化优先级state字段默认DetectorPriorityLevel.OKpriority_level属性转换为枚举与触发状态is_triggered数据库列名active配detector_state_triggered_date部分索引Redis 存储去重水位线dedupe watermarks与优先级阈值计数器带 TTL。对于StatefulDetectorHandler去重值必须是随源顺序递增的正整数水位线缺省为 0且 7 天后从 Redis 过期——意味着重复抑制不会超过该 TTL 持久化。2.DetectorGroup检测器 ↔ Issue Platform GroupDetectorGroup把 Issue Platform 的Group与产生/拥有它的检测器关联起来unique_together (group,)。检测器外键可空on_deleteSET_NULL删除后既有 issue 历史依然有效。关联通常在 Issue Platform 摄取期间创建兼容路径可回填缺失关联从 issue 反查检测器的调用方必须处理检测器已删除或缺失的情况。3.WorkflowActionGroupStatus重复频率抑制WorkflowActionGroupStatus记录(workflow, action, group)三元组上次通过重复频率过滤的时间唯一约束workflow_engine_uniq_workflow_action_group。它是在事件级去重与任务执行之前更新的因此不能证明外部动作确实完成。4.WorkflowFireHistory触发意图历史WorkflowFireHistory存储 Workflow、issue group、event IDCharField(max_length32)、notification UUIDUUIDField(auto_addTrue, uniqueTrue)以及可选的 detectoron_deleteSET_NULL。它没有动作或投递结果字段行在非活跃动作过滤与事件级去重之前创建所以记录的是派发前的意图而非已调度或成功投递的动作。索引包括(workflow, date_added, group)与(date_added)便于按工作流/时间线回溯。六、兼容模型Compatibility Models兼容关联模型负责把遗留的 issue 告警与 metric 告警记录映射到 Detector、Workflow、条件、动作与 Issue Platform 记录上。它们不参与常规的 Detector/Workflow 求值。完整的模型清单与当前混合读写行为参见 Legacy alert API compatibility。七、生命周期与失效Lifecycle and Invalidation创建CreationDetector 模型 API 创建由BaseDetectorTypeValidator协调在一个事务内创建或连接检测器的条件图、产品专属源对象、通用数据源、源映射与工作流默认检测器与工作流由 defaults/detectors.py 与 defaults/workflows.py 从项目/组织的 signal receiver 触发创建这些函数必须保持幂等配合分布式锁与缓存实测覆盖见 test_detectors.py 与 test_workflows.py。更新Updates对检测器、工作流、条件、源映射或动作映射的更新会失效缓存的处理图。receivers/中的 receiver 通常用transaction.on_commit()调度失效避免用未提交数据重建缓存。绕过校验器或关系模型的直写可能跳过 schema 校验、审计日志或缓存失效——官方建议优先走既有 validator 与服务路径。删除DeletionDetector API 删除会标记待删除PENDING_DELETION并调度 cell 删除任务相关 Issue Platform groups 与历史 fire 记录可能比检测器活得更久运行时查找必须容忍缺失记录。控制侧control-silo集成变更的动作清理走混合云ActionService。八、作用域与迁移Scope and RelocationWorkflow Engine 模型位于cell silocell_silo_model并按声明的__relocation_scope__参与 Sentry 的 relocation 框架。特别地DataSource需要特殊归一化其通用source_id必须用注册的 source handler 提供的模型名handler.get_relocation_model_name()在normalize_before_relocation_import中重新映射主键见 data_source.pyDetector、Workflow、DataCondition、DataConditionGroup、DataSourceDetector、DetectorWorkflow、WorkflowDataConditionGroup为RelocationScope.OrganizationAction、DataConditionGroupAction、DetectorState、DetectorGroup、WorkflowActionGroupStatus、WorkflowFireHistory为RelocationScope.Excluded不参与迁移。安全准则不要仅凭任意关联 ID 推断组织所有权API 查询必须显式限定到组织及其允许的项目参考DetectorQuerySet.by_organization的实现模式。九、推荐测试与扩展阅读官方文档推荐以下测试与工具作为深入验证的入口test_organization_project_detector_index.py演示事务化的检测器图创建test_detectors.py覆盖默认创建与锁test_workflows.py覆盖默认工作流图receivers 测试目录覆盖校验与缓存失效project_transfer.py项目迁移的克隆与重连辅助函数目前没有专属处理器测试是值得补足的空白点。配合阅读的关联文档还包括 Execution运行时控制流、Conditions条件求值契约与 Legacy alert API compatibility兼容模型。十、核心要点速查注册表即事实来源GroupType注册是检测器类型注册表data_source_type_registry、condition_handler_registry、action_handler_registry定义于 registry.py分别解析数据源、条件与动作的行为角色分离靠约定DataConditionGroup的三种角色检测器触发组 / WHEN 组 / IF 组不由数据库强制创建代码必须自觉隔离状态分存检测器优先级与触发状态在 PostgreSQL去重水位线与阈值计数器在 RedisTTL 7 天两者共同构成运行时契约历史表记录意图WorkflowFireHistory与WorkflowActionGroupStatus在派发/去重前写入不代表动作成功执行删除是软删除检测器删除标记PENDING_DELETION并异步清理group 与历史记录可能长存运行时必须容忍缺失迁移需重映射DataSource.source_id的通用引用在 relocation 导入时按 handler 模型名重建主键映射。【免费下载链接】sentryDeveloper-first error tracking and performance monitoring项目地址: https://gitcode.com/GitHub_Trending/sen/sentry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考