企业官网建设流程全解析

• 可观测性
• 后端
• 运维
• 前端
• 云原生
• 微服务
• AI Agent

本指南围绕 OneUptime 的Metrics Monitor（指标监控）展开，讲解如何对通过 OpenTelemetry 采集的自定义应用指标与基础设施指标（CPU、内存、磁盘、网络等）进行查询、公式组合、阈值判断与异常检测，并深入剖析其"按序列分组告警"（Group By）机制。读完本文，你将掌握从创建指标监控、配置查询与聚合策略，到编写多指标公式、设置静态阈值与基线异常检测，再到实现"每台主机一个告警"的完整实战方案。

概览：什么是 Metrics Monitor

Metrics Monitor 会查询并评估来自遥测服务的数值型指标，在设定的时间窗口内对指标值进行聚合，再依据你配置的判据（Criteria）触发告警。它支持的能力包括：

• 监控自定义应用指标，例如请求速率（request rate）、队列深度（queue depth）、错误率（error rate）等；
• 追踪基础设施指标，例如 CPU、内存、磁盘、网络；
• 通过过滤器（Attributes）与聚合（Aggregation）构建复杂的指标查询；
• 使用数学公式把多条指标组合成新的派生指标；
• 基于指标阈值（Threshold）设置告警，也支持无阈值的基线异常检测。

在 OneUptime 的监控体系中，Metrics Monitor 的数据来源是 OpenTelemetry（OTel）遥测管线：你的应用或基础设施必须先把指标发送到 OneUptime，监控才能查询到数据。这一点在 OpenTelemetry 接入文档 中有完整说明，后文"设置前提"一节也会再次强调。

创建 Metrics Monitor 的步骤

在 OneUptime Dashboard 中按以下流程创建：

1. 进入Monitors页面；
2. 点击Create Monitor；
3. 监控类型选择Metrics；
4. 配置一个或多个指标查询（Metric Query），并按需添加公式（Formula）；
5. 选择聚合策略（Aggregation Strategy）；
6. 按需配置监控判据（Monitoring Criteria）。

从数据模型上看，一个 Metrics Monitor 步骤由三部分构成（见 MonitorStepMetricMonitor.ts）：

• metricViewConfig：查询与公式的完整配置（queryConfigs+formulaConfigs）；
• rollingTime：评估时间窗口，默认值为Past1Minute；
• telemetryServiceIds（可选）：遥测服务范围限定，用于把监控限定到某个应用（如 RUM 推荐创建的监控），保持为空则作用于整个项目内所有匹配序列。

// MonitorStepMetricMonitor 默认值（源码节选） { metricViewConfig: { queryConfigs: [], formulaConfigs: [] }, rollingTime: RollingTime.Past1Minute, telemetryServiceIds: [], }

需要注意：监控步骤以 JSON 形式持久化，metricViewConfig在运行时可能缺失，因此代码中提供了getMetricViewConfig()防御性读取（见 MonitorStepMetricMonitor.ts），避免旧版本数据导致前端白屏。

配置选项详解

指标查询（Metric Queries）

一个查询定义一条要查询的指标序列，核心字段如下：

每个查询都会被分配一个别名（Alias），例如a、b、c，供公式引用。

在源码层面，查询配置对应 MetricQueryConfigData.ts 与 MetricQueryData.ts：

• metricAliasData：承载别名（metricVariable）、图表标题（title）与图例单位（legendUnit），见 MetricAliasData.ts；
• metricQueryData.filterData：包含metricName与属性过滤条件attributes；
• groupByAttributeKeys：OpenTelemetry 属性键数组（如host.name、service.name），当它被设置时，监控 Worker 会为每个唯一属性组合产出一条序列，从而支持"每台主机/每个服务各建一个告警"；
• topN：分组查询最多绘制多少个分组（默认上限 10）；
• transformAsRate：对于 OTel 的累计计数器（如system.disk.io、system.network.io），把数据点转换为每秒变化率(value - previousValue) / Δt，避免画出单调递增的累计值。

聚合类型在 AggregationType.ts 中定义，除文档提到的Max、Min、Sum、Avg、Count之外，还支持百分位聚合P50、P90、P95、P99（对直方图桶数据使用quantileExactWeighted计算），可用于对http.server.request.duration这类直方图指标做 P95 告警。

公式（Formulas）

公式用于把多条查询组合成数学表达式，每个公式同样拥有自己的别名。常用形式：

• a / b * 100— 由两条查询计算百分比；
• a + b— 两条指标求和；
• a - b— 两条指标求差。

公式定义对应 MetricFormulaConfigData.ts（含metricFormulaData.metricFormula表达式与别名元数据）。评估时，Worker 会按别名索引到对应查询或公式的聚合结果（查询与公式共享同一索引空间，公式索引偏移量为查询数量，见 MetricMonitorCriteria.ts）。公式还支持嵌套：一个公式可以引用另一个公式的别名。

滚动时间窗口（Rolling Time Window）

选择指标评估的时间窗口，文档列出的选项为：

• 过去 1 分钟（Past 1 Minute）
• 过去 5 分钟（Past 5 Minutes）
• 过去 10 分钟（Past 10 Minutes）
• 过去 15 分钟（Past 15 Minutes）
• 过去 30 分钟（Past 30 Minutes）
• 过去 60 分钟（Past 60 Minutes）

在 RollingTime.ts 中，枚举值从Past1Minute一直覆盖到Past365Days（按天级窗口用于指标浏览/图表场景），监控默认窗口为 1 分钟。窗口越大，参与评估的样本越多，对瞬时抖动越不敏感。

聚合策略（Aggregation Strategy）

聚合策略决定窗口内的所有采样值如何"折叠"成一个参与判据比较的结果：

该枚举对应源码 CriteriaFilter.ts 中的EvaluateOverTimeType。当判据未显式指定聚合类型时，评估器会回退到AnyValue（见 MetricMonitorCriteria.ts）。这与"按序列分组告警"配合尤其重要：例如"任何一台主机的磁盘用量超过 90% 就告警"应选择Any Value，而"所有主机都超过阈值才告警"则应选择All Values。

监控判据（Monitoring Criteria）

评估对象

Metrics Monitor始终评估"指标值"（Metric Value）——即配置的查询或公式在窗口内聚合后的数值。判据表单没有过滤器类型（Filter Type）选择器，而是直接展示Metric（指标）、Aggregation（聚合）、Condition（条件）与Threshold（阈值）。

静态阈值条件

静态阈值会把聚合值与你在Threshold中输入的数值比较：

• Greater Than（大于）— 指标值超过阈值；
• Less Than（小于）— 指标值低于阈值；
• Greater Than or Equal To（大于或等于）— 指标值达到或超过阈值；
• Less Than or Equal To（小于或等于）— 指标值处于或低于阈值；
• Equal To（等于）— 指标值与阈值完全相等。

源码中的比较逻辑见 MetricMonitorCriteria.ts 的sampleBreaches()，与文档列表一一对应，另支持NotEqualTo（不等于）。比较时还会做单位换算：采样值已按查询配置的legendUnit归一化，若阈值指定了不同的thresholdUnit，评估器会先把样本从legendUnit换算到阈值单位再比较（见 MetricMonitorCriteria.ts）。

无数据策略（NoData Policy）

虽然文档主表未单列，源码 CriteriaFilter.ts 明确支持三种无数据策略，值得在实战中配置：

• Ignore（默认）：把"窗口内没有任何数据"当作不触发，最安全，符合多数 SaaS 工具的默认行为；
• Treat As Zero：把缺失数据点当作 0，适合"没有事件就代表 0"的计数器场景；
• Trigger：无论阈值如何，直接把无数据判为违约，适合心跳类指标——"数据消失本身即故障"。

评估器在samples.length === 0时按上述策略分支处理（见 MetricMonitorCriteria.ts），避免"静默把无数据当 0 而误报"。

基线异常检测（Baseline Anomaly Detection）

不需要手工输入阈值；判据表单此时展示Sensitivity（灵敏度）与Baseline Window（基线窗口），系统会把每个采样点与"基于该窗口构建的、同小时同星期（hour-of-week）基线"比较：

• Anomalously High（异常偏高）— 指标值高出预期区间；
• Anomalously Low（异常偏低）— 指标值低于预期区间；
• Anomalous（异常）— 指标值向任意方向偏离预期区间。

异常条件会保持在Learning（学习中）状态，直到积累的指标历史至少达到所选的基线窗口长度之前，不会产生任何告警。这是冷启动保护：基线样本不足时绝不误报。

源码实现位于 MetricMonitorCriteria.ts 的evaluateAnomaly()中，要点如下：

• 基线按"星期几的第几小时"（hour-of-week）分桶建立，评估窗口若跨越小时边界，会同时拉取两个桶的基线；
• 灵敏度映射为标准差倍数：expectedHigh = mean + sigmaCount × stddev、expectedLow = mean - sigmaCount × stddev，超出该区间即违约；
• 基线状态机为Learning/Normal/Anomalous三态（见 MetricCriteriaContext.ts）：冷启动或样本不足时为Learning（不触发），基线可靠且未越界为Normal，越界为Anomalous（触发）；
• 默认基线窗口为 14 天（DEFAULT_WINDOW_DAYS），灵敏度枚举为 Low / Medium / High；
• 当前版本公式不支持异常检测（公式没有可基线的指标名，评估器直接返回 Learning 不触发），仅普通指标查询可用；
• 根因信息会报告观测值与基线均值的偏离标准差数（observedSigma），例如"偏差 3.2σ"。

异常检测单元换算有专门测试覆盖（见 MetricMonitorCriteriaAnomalyUnits.test.ts），验证均值、标准差与观测值均按人类可读比例显示、σ 保持纯数字、比率类指标按百分比呈现。

判据示例

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

• 查询 a：http_requests_total，过滤条件status=5xx；
• 查询 b：http_requests_total（全部请求）；
• 公式：a / b * 100；
• 条件：Greater Than（大于）；
• 阈值：5。

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

• 查询：request_queue_size，聚合方式选Maximum Value（最大值）；
• 条件：Greater Than；
• 阈值：1000。

按序列告警（Per-Series Alerting / Group By）

Group By会把一条指标查询按属性拆成"每个唯一属性值一条序列"——每台主机、每个容器、每个挂载点各一条。设置了 Group By 的监控会独立评估每一条序列。这一个设置，就是"整个集群不健康"与"prod-db-01这台机器不健康"之间的差别。

每分组一个告警

以host.name分组为例：一个磁盘用量监控同时看着五十台主机，每台越限的主机都会触发一条独立的告警（或事件 Incident）。主机 A 磁盘写满会打开它自己的告警；十分钟后主机 B 写满，会在旁边打开第二条彼此独立的告警。

如果不设置 Group By，同一个监控退化为一个标量：查询把全部主机的数据折合成一个数字，整个监控只能产生一条告警。在这条告警未关闭期间，第二台主机越限不会产生任何新东西——监控已经在告警了，没有"新事件"可建，值班工程师永远不会知道主机 B 出问题。设置 Group By 是获得"每主机告警"的唯一途径。如果你想按主机、按容器或按挂载点被呼叫（page），务必设置它。

源码层面的实现路径是：查询配置了groupByAttributeKeys后，Worker 在 MetricMonitorResponse.ts 中产出seriesBreakdown——每个序列携带一个fingerprint（指纹，由标签值稳定拼接而成）、labels（标签字典）以及仅限该序列的聚合结果（含逐序列公式结果），见 MetricSeriesResult.ts。评估器evaluateAllSeries()对每条序列独立执行同一判据（见 MetricMonitorCriteria.ts），调用方再按违约序列逐个创建事件。对应测试见 MetricMonitorCriteria.test.ts：三条序列（两台越限、一台正常）只返回两个违约结果，且各自携带独立的 breaching-samples 上下文。

独立解决（Independent Resolution）

每个分组告警只跟踪自己的分组。主机 A 回落到阈值以下后，A 的告警自动解决；主机 B 的告警会一直保持打开，直到 B 恢复。一个分组恢复绝不会关闭另一个分组的告警。

判据评估的差异

• 分组监控会评估每一条判据。因此多个严重程度带可以同时在不同分组上生效：当"Critical（严重）— 大于 95"排在"Warning（警告）— 大于 80"之上时，96% 的主机在同一次检查中触发严重告警，而 85% 的主机同时触发警告告警。同一台主机即使同时越过两个带，也只得到恰好一条告警——来自第一条匹配的判据，所以请把最严重的判据排在前面。
• 未分组监控在第一条匹配的判据处停止。只有那一条判据会触发，这是把"告警判据放在健康判据之上"的另一个理由：一条宽泛的健康判据如果排在前面，几乎每次检查都会匹配，从而让排在它下面的告警判据永远得不到评估。

如何选择分组属性

按"你确实会因为某个独立实体而呼叫某人"的属性来分组：

• 面向整个集群的主机指标 → 用主机属性（如host.name）；
• 容器指标 → 用容器或 Pod 属性；
• 文件系统或磁盘 I/O 指标 → 用挂载点（mountpoint）或设备属性；
• 网络指标 → 用接口（interface）属性。

Group By 下拉列表由你的 Collector 实际发送的属性填充，所以应从列表中选择，而不是手敲键名。反之，不要对本来就是全系统标量的指标分组——例如集群级 leader 标志、调度器积压、或单主机监控上的单台主机 CPU。给这类指标分组只会产生恰好一条序列，除了告警标题外什么都改变不了。

分组属性的值还可以作为模板变量用在告警或事件的标题、描述与修复备注中——按host.name分组后，标题可以显示为Disk almost full on {{host.name}}。

设置前提

指标监控要求你的应用或基础设施通过 OpenTelemetry 把指标发送到 OneUptime。完整的接入指引见 OpenTelemetry 文档，包括主机 Collector、Kubernetes、Docker、Serverless 等场景的采集配置。只有数据进入 OneUptime 的指标存储后，Metrics Monitor 的查询、公式与判据评估才有数据可依；这也是"Learning 状态"与"无数据策略"得以存在的底层原因——它们都在处理"数据不完整"这一现实约束。

小结

Metrics Monitor 是 OneUptime 面向数值型遥测指标的通用告警引擎：查询 + 公式定义"看什么"，滚动窗口 + 聚合策略定义"怎么算"，静态阈值 + 基线异常定义"何时告警"，而 Group By 则把"一个监控"升级为"按实体（主机/容器/挂载点/接口）独立评估与独立告警"的舰队级监控能力。建议按以下顺序落地：先确认 OpenTelemetry 指标已入库，再创建查询与公式，接着选好窗口与聚合策略，最后用分组 + 多级判据（严重 > 警告 > 健康）把告警粒度收敛到你需要被呼叫的最小实体。

• 可观测性
• 后端
• 运维
• 前端
• 云原生
• 微服务
• AI Agent