企业官网建设流程全解析

OneUptime 指标监控（Metrics Monitor）完全指南：基于 OpenTelemetry 的指标阈值与异常检测

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

本指南系统讲解 OneUptime 的指标监控（Metrics Monitor）功能：如何通过 OpenTelemetry 采集应用与基础设施的数值型指标，在控制台配置查询、公式与滑动时间窗口，并基于阈值或基线异常检测规则触发告警。读完本文，你将掌握指标监控的完整配置链路、底层判定原理以及可落地的实战示例（如错误率百分比告警、队列深度告警）。

一、指标监控是什么

指标监控（Metrics Monitor）是 OneUptime 监控体系中的一种监控器类型，用于查询并评估来自遥测服务的数值型指标。与 HTTP、Ping 等以探测结果为依据的监控器不同，指标监控直接作用于由 OpenTelemetry 采集到的度量数据，在指定的时间窗口内对指标值进行聚合与判定，当满足配置的告警条件时触发告警。

官方文档（metrics-monitor.md）对其能力做了如下定位：

• 监控应用自定义指标（如请求速率、队列深度、错误率等）；
• 跟踪基础设施指标（如 CPU、内存、磁盘、网络）；
• 使用过滤与聚合构建复杂指标查询；
• 通过数学公式组合多个指标；
• 基于指标阈值建立告警规则。

在源码层面，每个指标监控步骤由 MonitorStepMetricMonitor.ts 描述，其核心配置结构为：

export default interface MonitorStepMetricMonitor { metricViewConfig: MetricsViewConfig; rollingTime: RollingTime; telemetryServiceIds?: Array<ObjectID> | undefined; }

其中metricViewConfig包含查询列表queryConfigs与公式列表formulaConfigs，rollingTime即滑动时间窗口。默认情况下监控器会查询项目内所有匹配的指标序列；若配置了telemetryServiceIds（例如推荐系统自动创建的 RUM 监控器），则仅关注指定应用的指标。

二、前置条件：指标数据入口

指标监控的前提是应用或基础设施已将指标通过 OpenTelemetry 发送至 OneUptime。指标数据进入平台后，由 MetricType 等模型描述指标类型与原生单位，聚合查询在 ClickHouse 侧执行。

配置采集端时，请参考 OpenTelemetry 文档 完成 SDK/采集器的安装与导出地址配置。只有持续上报指标，监控器才能获得用于评估的样本序列。

三、创建指标监控器

在 OneUptime 控制台按以下步骤创建一个指标监控器：

1. 进入Monitores（监控器）页面；
2. 点击Crear monitor（创建监控器）；
3. 选择Métricas（指标）作为监控器类型；
4. 配置一个或多个指标查询，以及可选的公式；
5. 选择聚合策略；
6. 按需配置监控条件（criteria）。

创建完成后，监控器会周期性执行：拉取时间窗口内的指标样本 → 按聚合策略汇总 → 逐样本与阈值/基线比较 → 判定是否触发告警。该判定链路由 MetricMonitorCriteria.ts 实现，我们将在后文展开。

四、配置项详解

4.1 指标查询（Queries）

每个查询包含以下字段：

在源码中，查询由 MetricQueryConfigData.ts 承载，其中metricQueryData描述实际的查询语义（指标名、过滤属性、聚合、分组），metricAliasData则为查询分配一个别名变量（如a、b、c）供公式引用。

聚合类型定义在 AggregationType.ts 中：

enum AggregationType { Max = "Max", Min = "Min", Sum = "Sum", Avg = "Avg", Count = "Count", P50 = "P50", P90 = "P90", P95 = "P95", P99 = "P99", }

需要特别说明的是，除 Sum/Avg/Min/Max/Count 之外，平台还支持百分位聚合 P50/P90/P95/P99。对携带直方图桶数据的指标（如http.server.request.duration），MetricService 会先按桶展开为加权样本再计算quantileExactWeighted，从而得到基于桶的百分位数；对其他模型（Span、Log 等）则退化为 ClickHouse 的quantile(p)计算。从源码结构看，这部分逻辑位于 MetricService 的聚合路径中。

4.2 公式（Fórmulas）

公式允许你用数学表达式组合多个查询的结果，每个查询通过别名被引用：

• a / b * 100：计算两个查询的百分比（例如错误率）；
• a + b：两个指标求和；
• a - b：两个指标的差值。

公式在 MetricFormulaEvaluator 中解析与求值，公式所引用的变量会被解析为对应的查询/公式组件（见 MetricMonitorCriteria.ts 的buildFormulaComponents），从而在告警根因中标注每个组件对应的指标名与单位。

4.3 滑动时间窗口（Ventana de tiempo deslizante）

指标监控使用滑动窗口评估指标，可选项为：

• 最近 1 分钟
• 最近 5 分钟
• 最近 10 分钟
• 最近 15 分钟
• 最近 30 分钟
• 最近 60 分钟

窗口值由 RollingTime.ts 定义（如Past1Minute = "Past 1 Minute"、Past5Minutes、Past10Minutes、Past15Minutes、Past30Minutes、Past1Hour），并在创建/编辑表单中通过RollingTimePicker选择（见 MetricMonitorStepForm.tsx）。默认值为Past1Minute。

4.4 聚合策略（Estrategia de agregación）

在评估实现中，metricAggregationType缺省时会回退为EvaluateOverTimeType.AnyValue（见 MetricMonitorCriteria.ts），即“任一值满足即告警”的宽松语义。

4.5 无数据策略（补充能力）

从源码可以看到，评估器还支持对“窗口内无数据”的显式处理（onNoDataPolicy，默认Ignore）：

• Ignore：无数据时不触发告警（默认）；
• Trigger：无数据直接按违反条件触发告警；
• TreatAsZero：将无数据当作 0 参与比较。

该守卫避免监控器在尚未收到数据时被静默当作 0 处理而产生误报，实现在 MetricMonitorCriteria.ts。

4.6 单位换算（补充能力）

阈值比较前，样本值会先由MetricResultUnitConverter统一换算为用户在图例中选择的显示单位（legendUnit），再换算为阈值单位进行比较，确保告警消息以用户选择的单位呈现。对于system.filesystem.utilization这类原生单位为无纲量“1”的比率指标，代码会优先使用用户选择的 legendUnit，否则回退到从 MetricType 加载的原生单位，避免“%”阈值无法与原始 [0,1] 样本比较（见 MetricMonitorCriteria.ts 与buildContext）。

五、监控条件（Criterios de monitoreo）

5.1 可用的检查类型

当checkOn不是CheckOn.MetricValue时，评估器直接返回空结果（见 MetricMonitorCriteria.ts）。

5.2 阈值过滤类型

• Mayor que（大于）：指标值超过阈值；
• Menor que（小于）：指标值低于阈值；
• Mayor o igual que（大于等于）：指标值达到或超过阈值；
• Menor o igual que（小于等于）：指标值处于或低于阈值；
• Igual a（等于）：指标值与阈值精确匹配。

底层比较逻辑位于 MetricMonitorCriteria.ts 的sampleBreaches，它对每个样本执行value > threshold、value >= threshold、value < threshold、value <= threshold、value === threshold等判定。

5.3 基线异常检测（Detección de anomalías）

不设置阈值时，表单会展示Sensibilidad（灵敏度）与Ventana de línea base（基线窗口）两个配置项，系统将每个样本与同一周时刻（hour-of-week）的历史基线进行比较：

• Anómalamente alto（异常偏高）：值高于期望范围；
• Anómalamente bajo（异常偏低）：值低于期望范围；
• Anómalo（异常）：值向任一方向偏离期望范围。

异常判定的核心原理（见 MetricMonitorCriteria.ts 的evaluateAnomaly）：

1. 按灵敏度（Sensitivity，默认 Medium）映射出 sigma 倍数，sigmaCount = MetricBaselineService.sigmaForSensitivity(sensitivity)；
2. 对窗口内每个样本，根据其时间戳计算hourOfWeek，并从 MetricBaselineService 获取该小时的基线摘要（mean、stddev 及可靠性标记）；
3. 计算期望区间[mean - sigma*stddev, mean + sigma*stddev]，样本越界即视为异常；
4. 基线缺失或不可靠（冷启动）时进入Learning（学习）状态，不触发告警，且窗口内无足够历史数据时同样保持 Learning——这正是文档所述“至少存在所配置的基线窗口历史后才产生告警”的实现保证；
5. 正常时状态为Normal，命中时状态为Anomalous并携带期望区间、观测值与 sigma 等上下文。

需要指出的是，公式型条件在 v1 中不支持异常检测（公式没有可基线化的指标名，代码会跳过并保持 Learning 状态），这是源码 evaluateAnomaly 中的显式限制。

5.4 分组序列与逐序列告警（补充能力）

若监控器配置了分组维度（groupBy），指标响应会携带seriesBreakdown，每个分组序列拥有独立的 fingerprint 与 labels。评估器会对每个序列分别执行判定（evaluateAllSeries），并为每个违规序列生成独立的告警上下文，其根因信息中包含该序列的违规样本表、分组标签及公式组件值（见 MetricMonitorCriteria.ts）。未分组时则退化为对所有聚合结果的单一评估（兼容旧行为）。

六、实战示例

6.1 示例一：错误率超过 5% 时告警

| 配置项 | 值 | | ------ | -- | | 查询 a |http_requests_total，过滤status=5xx| | 查询 b |http_requests_total| | 公式 |a / b * 100| | 检查项 | 指标值（Valor de métrica） | | 过滤类型 | Mayor que（大于） | | 阈值 | 5 |

实现要点：查询 a 与查询 b 分别被赋予别名（如a、b），公式计算两者百分比；评估器通过别名定位到对应的聚合结果（evaluateOneSeries），公式命中后还会在根因中回填a、b各自在违规时刻的值（buildComponentValueLookup+resolveComponentValues），便于排查。

6.2 示例二：请求队列深度过高时告警

| 配置项 | 值 | | ------ | -- | | 查询 |request_queue_size，聚合方式：最大值（Valor máximo） | | 检查项 | 指标值 | | 过滤类型 | Mayor que（大于） | | 阈值 | 1000 |

该示例利用 Max 聚合捕捉窗口内队列深度的峰值，避免平均值掩盖短时尖峰。

七、小结

OneUptime 指标监控打通了“OpenTelemetry 采集 → ClickHouse 存储与聚合 → 查询/公式/窗口配置 → 阈值与异常判定 → 逐序列告警”的完整链路。本文介绍的查询、公式、滑动窗口、聚合策略、无数据策略、单位换算与基线异常检测等能力，均有对应的类型定义与判定实现可查证（见 MonitorStepMetricMonitor.ts、MetricMonitorCriteria.ts 及其测试 MetricMonitorCriteria.test.ts）。配置指标监控前，请务必先完成应用的 OpenTelemetry 指标上报，并合理选择窗口大小与聚合策略，以平衡告警灵敏度与误报率。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime