OneUptime Traces Monitor 使用指南基于 OpenTelemetry Span 的分布式链路告警配置与实现原理【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeTraces Monitor链路监控是 OneUptime 遥测类监控的一种它允许你在分布式跟踪Distributed Tracing数据之上建立告警对指定遥测服务产出的 span 按状态、名称、自定义属性等条件进行过滤与计数一旦匹配数量越过阈值即触发告警。读完本文你将掌握 Traces Monitor 的完整配置方法服务选择、Span 过滤、时间窗口、阈值条件、两个可直接套用的实战告警示例以及从配置到查询、评估的源码级实现原理。Traces Monitor 是什么Traces 监控的核心行为是在时间窗口内检索并统计符合特定过滤条件的 span 数量。它不关心单条 trace 的内部耗时细节而是把链路数据的整体形态作为监控对象。基于这一模型你可以实现对服务中的错误 span 尖峰进行告警例如 60 秒内 ERROR span 超过 50 条监控特定操作与端点例如POST /api/checkout这个 span 一旦出现错误即告警跟踪span 数量与模式的变化趋势按 span 状态、名称与自定义属性进行精细过滤从 trace 数据中提前发现性能与可靠性问题而无需人工盯查追踪面板。从项目类型定义看Traces与Logs、Metrics、Exceptions、Profiles、SecurityEvents同属于Telemetry类别监控见 MonitorType.ts它们在 MonitorTypeHelper.getMonitorTypeCategories() 中被归入 Telemetry 分组同时isTelemetryMonitor也表明这类监控的数据并非来自探测端Probe主动探测而是由应用通过 OpenTelemetry 上报。工作原理从配置到查询与评估理解 Traces Monitor 的内部机制有助于正确配置。它的核心数据链路在源码中清晰可循配置模型每个监控步骤携带一份MonitorStepTraceMonitor配置见 MonitorStepTraceMonitor.ts包含telemetryServiceIds遥测服务、spanStatuses状态、spanName名称、attributes属性键值对、entityKeys可选的主机/容器等实体键以及lastXSecondsOfSpans回溯秒数默认 60。查询构建MonitorStepTraceMonitorUtil.toQuery()见 MonitorStepTraceMonitor.ts把这五类配置编译为对 Span 分析表的数据库查询telemetryServiceIds→ 按服务主键primaryEntityId做Includes匹配entityKeys→ 对entityKeys列做Includes匹配空则不生效attributes→ 直接按属性列精确匹配spanStatuses→ 对statusCode列做Includes匹配spanName→ 对name列做全文检索SearchlastXSecondsOfSpans→ 用当前时间回推 N 秒构造startTime的InBetween区间。计数响应评估端拿到的是 TraceMonitorResponse核心字段即spanCount命中查询的 span 数量。阈值判定TraceMonitorCriteria.isMonitorInstanceCriteriaFilterMet() 读取checkOn为Span Count对应枚举 CheckOn.SpanCount的过滤条件将spanCount与阈值经CompareCriteria.compareCriteriaNumbers()比较命中即返回告警信息文本。监控调度Traces 属于isProbableMonitor之外的服务端评估型遥测监控数据持续由遥测服务上报监控按周期对时间窗口内数据做滚动评估。创建 Traces Monitor在 OneUptime 控制台按以下步骤创建一个 Traces 监控进入仪表盘的Monitors监控页面点击Create Monitor创建监控在监控类型选择器中选中Traces链路类型定义见 MonitorType.ts其描述为 Alert on span latency and error rate from any source选择要监控的遥测服务一个或多个按需配置Span 过滤器与监控条件Criteria保存并启用随后可关联通知规则如邮件、Slack、电话等接收告警。配置项详解Traces Monitor 的配置即traceMonitor步骤由以下几个维度组成与仪表盘表单字段一一对应可对照 MonitorStepViewModel.ts 的渲染逻辑。遥测服务Telemetry Services选择一条或多条需要从中检索 span 的服务。这些服务必须已经通过 OpenTelemetry 将 trace 数据上报到 OneUptime监控才能检索到 span。在源码中对应telemetryServiceIds查询时按primaryEntityId过滤。实体键Inventory Items可选除服务维度外还可把监控范围进一步限定到具体的主机host、Pod 或容器等实体——即entityKeys。该字段为可选旧版本保存的监控没有此字段新配置留空则不对实体做限定参见 MonitorStepTraceMonitor.ts 的注释说明。仪表盘中显示为 Inventory Items。Span 过滤器过滤器说明是否必填Span 状态Span Statuses按 span 状态码过滤OK / ERROR / UNSET否Span 名称Span Name按文本检索特定 span 名称如操作名、端点名否属性Attributes键值对按自定义 span 属性过滤否时间窗口Time Window回溯多少秒内的 span默认 60 秒否过滤器的语义在源码中非常直接span 状态与属性、服务为精确匹配span 名称走全文搜索时间窗口决定startTime区间。留空的过滤器不参与查询因此不填状态意味着监控所有状态的 span仪表盘占位文案为 All statuses will be monitored。Span 状态码OpenTelemetry 约定的 span 状态在 Span.ts 中定义为数值枚举状态数值含义OK1操作成功完成ERROR2操作遇到错误UNSET0未显式设置状态配置时可按语义选择任意组合在查询构建阶段会展开为statusCode IN (...)。监控条件Criteria监控条件决定了什么时候触发告警。Traces Monitor 目前提供的检查维度如下。可用检查类型检查类型说明Span 数量Span Count时间窗口内匹配过滤器的 span 总数对应枚举值CheckOn.SpanCountSpan Count见 CriteriaFilter.ts。评估时取出spanCount与阈值比较。过滤器类型Filter Types针对 Span 数量支持以下比较类型枚举定义见 CriteriaFilter.tsGreater Than大于span 数量超过阈值Less Than小于span 数量低于阈值Greater Than Or Equal To大于等于span 数量达到或超过阈值Less Than Or Equal To小于等于span 数量低于或等于阈值Equal To等于span 数量精确等于阈值。补充说明FilterType枚举中还包含Anomalously High/Anomalously Low/Anomalous三类异常检测过滤类型。Traces 监控的评估器同样支持该路径见下文异常检测小节它会忽略静态阈值改为与历史基线比较。示例一60 秒内超过 50 条错误 span 即告警一个直接可用的错误尖峰告警配置Span 状态ERROR时间窗口60 秒检查类型Span 数量过滤器类型Greater Than大于阈值50适用场景服务出现批量失败时快速报警用于捕捉异常错误爆发而非零星错误。示例二特定端点出现错误即告警对单个业务端点的零容忍告警Span 名称POST /api/checkoutSpan 状态ERROR时间窗口120 秒检查类型Span 数量过滤器类型Greater Than大于阈值0适用场景关键交易链路如下单一旦出现任何错误就立刻通知适合对核心 API 的可靠性进行严格守护。前置要求通过 OpenTelemetry 上报链路数据Traces 监控的前提是应用已经通过 OpenTelemetry 向 OneUptime 上报分布式 trace。接入步骤概述如下在 OneUptime 项目设置的Telemetry Ingestion Key遥测采集密钥页面创建采集令牌在应用中配置 OpenTelemetry SDK并将 OTLP 端点指向 OneUptime填入采集令牌确认服务列表中出现对应遥测服务后再创建 Traces Monitor。详细接入步骤参见仓库内的 OpenTelemetry 接入文档包含采集令牌创建、环境变量配置与各语言 SDK 指引。进阶Span 数量的异常检测Anomaly Detection除了固定阈值Traces Monitor 还内置了基于基线的异常检测路径实现在 TraceMonitorCriteria.evaluateSpanCountAnomaly()。其机制可概括为把观测到的 span 数量归一化为每分钟速率spanCount × 60 / windowSeconds通过SpanCountBaselineService.getBaseline()读取同小时段hour-of-week滚动基线基线范围限定到该监控的服务与 span 状态属性与名称过滤器不参与基线基线是这一范围的完整总量根据灵敏度sensitivityLow / Medium / High默认 Medium换算 sigma 倍数选择统计方法默认Mean Std Dev另有Median MAD以抵抗长尾分布冷启动保护基线样本不足minSamples或不可靠时不告警避免刚上线误报零方差基线同样跳过评估通过则产出包含观察值、偏离 σ、基线均值/中位数、样本数、窗口天数、灵敏度的完整告警文本。相关参数windowDays默认 14 天、minSamples位于 CriteriaFilter.ts 的MetricAnomalyDetectionOptions中与指标监控共用一套配置结构。需要发现异常而不设硬阈值的场景例如流量突降、错误率隐性抬升可直接选用Anomalously High/Anomalously Low过滤类型。小结Traces Monitor 把 OpenTelemetry 的 span 数据转化为可配置、可计数的告警来源通过服务 状态 名称 属性 时间窗口的组合过滤定位关注范围再以 Span 数量配合五种比较类型触发告警如需更智能的检测还可启用基于小时级基线的异常检测路径。配合 OpenTelemetry 接入文档 完成数据上报后即可在 Monitors 页面创建你的第一个 Traces Monitor将分布式链路的健康状态纳入统一的告警体系。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考