企业官网建设流程全解析

VictoriaMetrics 流式聚合配置指南：streamAggr 配置格式、聚合函数与热加载实战

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics

导读：本文以 docs/victoriametrics/stream-aggregation/configuration.md 为核心主体，系统讲解 VictoriaMetrics 单机版（single-node VictoriaMetrics）与 vmagent 中流式聚合（stream aggregation）的完整配置体系，包括命令行参数、YAML 配置文件中每个字段的语义与默认值、聚合输出的 19 种函数（outputs）的度量语义与等价 MetricsQL 表达式，以及 SIGHUP //-/reload两种热加载方式。文中同时结合仓库 lib/streamaggr 目录下的源码实现（配置解析、状态机、去重、flush 调度等）进行印证，帮助读者既能照配置上手，又能理解底层行为，最终具备在生产环境编写、调试并维护流式聚合规则的能力。

一、流式聚合是什么：数据在写入前先被“压缩”

流式聚合（stream aggregation）是 VictoriaMetrics 提供的一项实时预聚合能力：在 vmagent 或单机版 VictoriaMetrics 将数据写入存储之前，先按照时间窗口与标签维度对输入样本进行聚合，再写入聚合结果。其价值在于：

• 大幅降低写入存储的样本数量与时间序列（series）数量，节省磁盘空间与查询开销；
• 替代部分 Recording rules 的实时计算负担；
• 可作为 StatsD 类计数/求和/分位数聚合的替代方案；
• 支持通过-streamAggr.keepInput/-streamAggr.dropInput灵活控制原始样本的去留，构建多级处理管道。

架构示意（来自 docs/victoriametrics/stream-aggregation/README.md）：

流式聚合的局限性需要明确（同见 docs/victoriametrics/stream-aggregation/README.md）：

• 默认按样本的摄入时间（ingestion time）而非样本自带时间戳处理，旧样本默认会被计入聚合；
• 聚合状态保存在进程内存中，进程重启后状态丢失（可通过-streamAggr.ignoreFirstIntervals、flush_on_shutdown等缓解）。

二、启用流式聚合的命令行参数

流式聚合通过如下命令行参数启用，参数值均指向一个包含流式聚合配置的 YAML 文件：

配置文件中支持%{ENV_VAR}占位符，运行时会被替换为对应环境变量的值。这一机制与组件其他环境变量展开逻辑一致，相关实现可参考 lib/envtemplate/envtemplate.go。

原始输入样本的去留控制

启用流式聚合后，默认写入存储的数据有两类：

1. 聚合后的样本；
2. 未匹配任何聚合规则match的原始输入样本。

该默认行为可通过以下参数改变：

• -streamAggr.keepInput（单机版 / vmagent；vmagent 上亦可按-remoteWrite.url单独指定-remoteWrite.streamAggr.keepInput）：设置后，匹配任一规则的输入样本也会被保留并写入存储；
• -streamAggr.dropInput（单机版 / vmagent；vmagent 上亦可按-remoteWrite.url单独指定-remoteWrite.streamAggr.dropInput）：设置后，未匹配任何规则的输入样本会被丢弃。

在源码层，-streamAggr.keepInput与keep_metric_names互斥——若两者同时开启会因时间序列命名冲突而报错（见 lib/streamaggr/streamaggr.go）。

三、Stream aggregation config：完整字段参考

以下为流式聚合配置文件格式的完整注释版。该文件通过-streamAggr.config或-remoteWrite.streamAggr.config引用，match采用任意 Prometheus series selector 语法：

# name 是可选配置名，若设置，将作为 /metrics 页面中该聚合配置暴露指标的 name 标签 - name: 'foobar' # match 是对输入样本的可选过滤条件，支持任意 Prometheus series selector # 也可配置为 series selector 列表，样本命中其中任意一个即参与聚合 # 未设置时，所有输入样本都会被聚合 match: 'http_request_duration_seconds_bucket{env=~"prod|staging"}' # interval 为聚合周期，聚合结果每个 interval 向远端发送一次 # 建议至少设为输入采集/推送周期的 2 倍；输入管道延迟大时可调大 interval: 1m # dedup_interval 为聚合前去重间隔，按序列粒度去重（per-series） # 去重发生在 input_relabel_configs 重打标之后 # 默认禁用，除非设置了 -streamAggr.dedupInterval 或 -remoteWrite.streamAggr.dedupInterval # dedup_interval: 30s # enable_windows 为布尔选项，开启固定聚合窗口（aggregation windows） # enable_windows: true # staleness_interval 为无新样本时的序列状态重置间隔，仅对以下输出生效： # histogram_bucket、increase、increase_prometheus、rate_avg、rate_sum、total、total_prometheus # staleness_interval: 1m # ignore_first_sample_interval 指定 agent 开始发送样本的延迟间隔 # 默认等于 staleness_interval，用于降低 agent 重启后的初始样本负载 # 仅对 total、total_prometheus、increase、increase_prometheus、histogram_bucket 输出生效 # ignore_first_sample_interval: 2m # no_align_flush_to_interval 禁用 flush 时间与 interval 整数倍对齐 # 默认对齐：interval: 1m 时每分钟末 flush；interval: 1h 时每小时末 flush # no_align_flush_to_interval: false # flush_on_shutdown 指示在 vmagent 启动/重启/配置热加载的首末区间也 flush 聚合数据 # 默认不 flush 不完整的聚合数据，因其通常具有误导性 # flush_on_shutdown: false # without 为从输出聚合中移除的标签列表 # without: [instance] # by 为输出聚合中需要保留的标签列表 # by: [job, vmrange] # outputs 为对输入数据执行的聚合函数列表（唯一） outputs: [total] # keep_metric_names 指示保留原始指标名（不加后缀） # 不可与 -streamAggr.keepInput 同时启用；仅当 outputs 只有一个聚合时可用 # 默认会给聚合指标名追加特殊后缀 # keep_metric_names: false # ignore_old_samples 指示忽略时间戳不在当前聚合区间内的旧输入样本 # 与 -streamAggr.ignoreOldSamples 命令行参数互相对应 # ignore_old_samples: false # ignore_first_intervals 指示进程启动后忽略前 N 个聚合区间 # 与 -streamAggr.ignoreFirstIntervals 命令行参数互相对应 # ignore_first_intervals: N # drop_input_labels 指示从输入样本中丢弃指定标签 # 丢弃发生在 input_relabel_configs 之前，因此也先于去重与聚合 # drop_input_labels: [replica, availability_zone] # input_relabel_configs 为可选重打标规则：作用于通过 match 过滤后的输入样本、聚合之前 input_relabel_configs: - target_label: vmaggr replacement: before # output_relabel_configs 为可选重打标规则：作用于聚合后的输出指标 output_relabel_configs: - target_label: vmaggr replacement: after

配置文件可包含多个聚合配置条目，每个条目独立执行聚合。

字段校验与默认值（源码印证）

lib/streamaggr/streamaggr.go 中的newAggregator是配置解析与校验的核心，可以从源码确认以下行为：

• interval必填且必须能被time.ParseDuration解析，且不得小于 1 秒；
• dedup_interval不能大于interval，且interval必须是dedup_interval的整数倍；
• staleness_interval默认等于interval（与 MetricsQL 查询回看窗口保持一致），且不能小于interval；
• by与without不能同时设置，否则初始化报错；两者都为空时退化为“仅按时间聚合”（aggregateOnlyByTime），即每个输入序列独立计算输出；当使用by时，源码会自动把__name__追加进分组标签（见addMissingUnderscoreName），保证不同指标名不会混聚；
• keep_metric_names与keepInput互斥；outputs列表必须至少包含一个条目，且不允许重复的聚合函数（quantiles(0.5,0.9)需合并写在一个函数内，不能写成两个quantiles条目）；
• by/without/输出后缀中的标签会先排序再去重（sortAndRemoveDuplicates），因此输出指标名是确定性的。

输出指标命名规则

默认情况下，聚合输出指标名按以下模式构造（详见 docs/victoriametrics/stream-aggregation/README.md 与 lib/streamaggr/streamaggr.go 中 suffix 的拼接逻辑）：

<metric_name>:<interval>[_by_<by_labels>][_without_<without_labels>]_<output>

• <metric_name>为原始指标名；
• <interval>为配置中的聚合周期；
• <by_labels>为by标签的_分隔排序列表，未设置by时不出现该段；
• <without_labels>为without标签的_分隔排序列表，未设置时不出现该段；
• <output>为outputs列表中的聚合函数名。

例如foo{app="bar",instance="host1"}在interval: 1m、outputs: [sum_samples]下输出foo:1m_sum_samples{app="bar",instance="host1"}；若配置without: [instance]则输出foo:1m_without_instance_sum_samples{app="bar"}；若配置by: [app]则输出foo:1m_by_app_sum_samples{app="bar"}。

设置keep_metric_names: true可保留原始指标名，但仅限单输出场景。实现上，suffix 最终在addMetricSuffix（lib/streamaggr/streamaggr.go）中追加到__name__标签上；若标签中缺失__name__，则自动补建。

四、配置热加载：两种方式，无需重启进程

单机版 VictoriaMetrics 与 vmagent 支持以下两种方式热加载-streamAggr.config/-remoteWrite.streamAggr.config配置：

1. 向进程发送SIGHUP信号：

   kill -SIGHUP `pidof vmagent`

2. 发送 HTTP 请求到/-/reload端点，例如：

   http://vmagent:8429/-/reload http://victoria-metrics:8428/-/reload

热加载后，聚合状态会以新配置重新初始化（源码中Aggregators.Equal()通过对比序列化的配置 JSON 判断是否需要重建，见 lib/streamaggr/streamaggr.go）。注意：热加载会丢失旧的聚合内存状态，且首末不完整区间的数据默认不 flush，因此线上变更规则时建议关注ignore_first_intervals与flush_on_shutdown的配合。

五、聚合输出函数（Aggregation outputs）全解析

聚合在每个interval内计算、每个interval向存储发送一次。若配置了by/without，还会在时间聚合之外附加按标签聚合。outputs列表支持以下 19 种聚合函数：

avg、count_samples、count_series、histogram_bucket、increase、increase_prometheus、last、max、min、rate_avg、rate_sum、stddev、stdvar、sum_samples、sum_samples_total、total、total_prometheus、unique_samples、quantiles(phi1, ..., phiN)。

下表汇总了各函数的适用指标类型与等价 MetricsQL 表达式（全部整理自 configuration.md）：

下面按类别详解各函数的行为要点（含源码级实现依据）。

5.1 计数与求和类：count_samples / count_series / sum_samples / unique_samples / sum_samples_total

• count_samples：统计给定interval内接收到的输入样本条数。典型用途是事件计数，例如广告服务器按请求产生hits{some="labels"} 1、clicks{some="labels"} 1，可用outputs: [count_samples]每 30 秒聚合出hits:30s_count_samples、clicks:30s_count_samples。
• count_series：统计给定interval内出现的唯一时间序列数量，用于衡量高基数（high cardinality）。
• sum_samples：对 gauge 样本值求和，适合将高频/不规则事件累加为周期性输出。
• unique_samples：统计给定interval内唯一样本值的个数。
• sum_samples_total（自 v1.146.0 起）：将输入 delta 值累加为累积 counter 并周期性输出，专用于 StatsD counter 这类“每次上报增量”的客户端。注意：若输出结果在staleness_interval（默认等于interval）内没有新输入，聚合器会遗忘累积值，下次输入时从 0 重新累计，需要容忍更大间隙时可调大staleness_interval。

5.2 极值与位置类：min / max / last / avg

• min/max：分别返回interval内输入样本的最小/最大值，适合仪表类数据。
• last：返回interval内最后一个输入样本值。
• avg：返回输入样本值的算术平均，仅对 gauge 有意义。

5.3 计数器类：increase / increase_prometheus / total / total_prometheus

这四类仅对 counter 有意义，核心区别在于新序列首个样本是否计入：

• increase：返回interval内输入 counter 的增量。它假设所有 counter 从 0 开始——例如新序列首个样本为10，则increase认为该序列增加了10。
• increase_prometheus：同样返回增量，但跳过每个时间序列的首个样本（与 Prometheus 的increase语义一致）。
• total：通过累加输入 counter 生成输出 counter，同样假设 counter 从 0 开始。total不受 counter reset 影响——遇到值回退会按重置处理并继续单调递增；Kubernetes 中 Pod 重启导致标签变化、聚合组内序列集合变化时，total也能保持状态不重置。
• total_prometheus：与total相同但跳过新序列首个样本。

源码印证：在 lib/streamaggr/increase.go 与 lib/streamaggr/total.go 中，二者都维护lastValues映射记录每个序列的上一个值：样本值 >= 上一值时累加差值，样本值 < 上一值时视为 counter reset、直接累加样本值并递增vm_streamaggr_counter_resets_total指标；乱序样本（timestamp 更小）会被直接跳过。

一个容易被忽略的实现细节：无论keepFirstSample如何设置，total/increase/total_prometheus/increase_prometheus在进程启动后的ignore_first_sample_interval（默认取 staleness interval，见 lib/streamaggr/streamaggr.go）时间窗口内都会忽略新序列的首个样本，这是为了避免 agent 重启后初始样本造成输出尖峰（见 total.go 的ignoreFirstSampleDeadline注释）。

5.4 速率类：rate_avg / rate_sum

• rate_avg：返回interval内各输入 counter 每秒增长率的平均。
• rate_sum：返回各输入 counter 每秒增长率的求和。

rate_sum是聚合直方图（histogram bucket 系列）的标准做法：直方图是一组带le或vmrange标签的 counter，对它们整体做rate_sum后可配合histogram_quantile计算分位数。实现细节参见 lib/streamaggr/rate.go，其中每个序列记录prevTimestamp与当前区间累计 increase，flush 时按increase / (timestamp - prevTimestamp)折算每秒速率。

5.5 分布类：stddev / stdvar / histogram_bucket / quantiles

• stddev/stdvar：分别返回interval内样本值的标准差与方差，仅对 gauge 有意义。
• histogram_bucket：将输入样本值聚合成 VictoriaMetrics 直方图分桶（vmrange标签形式），仅对 gauge 有意义。实现上使用metrics.Histogram累积并逐桶输出（lib/streamaggr/histogram_bucket.go）。聚合后可用histogram_quantiles、histogram_stddev、histogram_share等 MetricsQL 函数查询分位数、标准差与占比。
• quantiles(phi1, ..., phiN)：计算给定的一个或多个分位数，phi取值必须在[0..1]区间（0 为 0th 百分位，1 为 100th 百分位），仅对 gauge 有意义。实现上采用github.com/valyala/histogram的Fast直方图近似分位数（lib/streamaggr/quantiles.go），每个phi输出一条带quantile标签的序列；源码会校验quantiles(...)的括号闭合、参数非空、phi 范围，并拒绝重复的quantiles条目。

5.6 关键运维语义：counter reset 与数据延迟（staleness）

聚合计数器类输出前建议关注两个监控指标：

• vm_streamaggr_counter_resets_total：每次检测到 counter reset（值回退）时递增。若total*、rate*、increase*输出明显高于预期，应检查该指标，排查原始样本的重复或碰撞，必要时在聚合前开启去重。
• vm_streamaggr_samples_lag_seconds_bucket：样本延迟直方图。延迟会显著影响聚合正确性：
  • 输入样本延迟多个聚合周期时，聚合将出现输出空洞；
  • 延迟/乱序样本可能使结果虚高或偏移。
  • 对策：若追求结果一致性，用ignore_old_samples丢弃潜在延迟样本；若希望延迟数据反映到后续窗口，则应调大staleness_interval（默认等于interval，代码见 lib/streamaggr/streamaggr.go）。

六、与存储/查询的联动：聚合窗口与去重

6.1 聚合窗口（Aggregation windows）

默认情况下，流式聚合与去重对每个输出结果只保存单一状态，每个聚合区间独立 flush。靠近区间边界的样本（如interval: 1m时时间戳为 18:57:59 的样本）可能落入18:58:00或18:59:00两个区间之一，取决于网络延迟、负载与时钟同步。对普通指标这通常不影响结果，但对直方图这类“一组序列共同构成一个逻辑整体”的指标会导致聚合错误。

为此（自 v1.112.0 起）引入了固定聚合窗口模式：同时维护当前与上一区间的两份状态，flush 不立即执行，而是按观测到的样本延迟（flushAfterMsec）推迟，显著改善延迟样本下的计算精度。代价是内存占用翻倍。启用方式：

• -streamAggr.enableWindows（单机版 / vmagent；vmagent 可逐-remoteWrite.url指定-remoteWrite.streamAggr.enableWindows）：设置后所有聚合器均使用固定窗口；与-streamAggr.dedupInterval组合时去重器也启用固定窗口；
• 配置中的enable_windows: true：仅为某个聚合器启用。

源码层面，窗口模式在 lib/streamaggr/streamaggr.go 中以isGreen/blue双状态切换（currentState、aggrValues的 green/blue 数组）实现，Push 阶段按样本时间戳归属当前或上一状态，flush 阶段按flushAfterMsec动态延迟（lib/streamaggr/streamaggr.go）。

6.2 去重（Deduplication）

• 在vmagent中，可通过-streamAggr.dedupInterval=30s（对所有数据）或-remoteWrite.streamAggr.dedupInterval=30s（对特定-remoteWrite.url）开启发送前去重：每个时间序列每 30 秒只保留最后一个样本。去重发生在 relabeling 之后、聚合之前，亦可为单个聚合配置设置dedup_interval。
• 在单机版 VictoriaMetrics中，支持两类去重：入库后的-dedup.minScrapeInterval去重，以及入库前通过-streamAggr.dedupInterval/ 配置内dedup_interval实现的去重。
• 去重丢弃的旧样本可用vm_streamaggr_dedup_dropped_samples_total指标追踪；去重器内部为 128 分片并缓存行填充防止伪共享（lib/streamaggr/dedup.go）。

注意：若存储端启用了-dedup.minScrapeInterval而 vmagent 未配置去重，聚合结果可能与存储上的查询结果不一致（例如sum(rate(foo[1m])) by (instance)与rate_sum聚合结果存在差异）。建议将 vmagent 的-streamAggr.dedupInterval与存储端去重间隔保持一致。

七、数据流与处理顺序：Keep / Drop / Relabel 的组合

单机版 VictoriaMetrics 对接收的所有数据（抓取或推送）依次执行 relabeling、去重、流式聚合，处理后写入本地存储，不能继续转发。vmagent 的处理顺序见 vmagent 生命周期文档，典型路由场景：

1. 聚合后复制到 N 个远端：使用全局-streamAggr.config，聚合一次后复制到所有-remoteWrite.url；
2. 为每个远端独立聚合：为每个-remoteWrite.url分别指定-remoteWrite.streamAggr.config，配合-remoteWrite.urlRelabelConfig将选定指标路由到不同远端。

流式聚合还支持两级 relabeling：

• input_relabel_configs：作用于通过match过滤后的输入样本、在可选去重之前；
• output_relabel_configs：作用于聚合输出、在发送到远端存储之前。

常见用法：用output_relabel_configs去掉聚合指标名中的:1m_sum_samples后缀，或直接用keep_metric_names: true。例如：

- interval: 1m outputs: [sum_samples] output_relabel_configs: - source_labels: [__name__] target_label: __name__ regex: "(.+):.+"

标签的丢弃同样有三种途径（详见 README.md）：全局-streamAggr.dropInputLabels="replica,az"、按远端-remoteWrite.streamAggr.dropInputLabels（多个标签用^^分隔）、以及配置内drop_input_labels（优先级最高，先于 input relabeling 与去重执行）。

八、运维最佳实践与常见误区

结合 README.md 的 Troubleshooting 部分，以下实践值得牢记：

1. 把聚合器放在负载均衡之后是错误的：聚合正确性依赖同一聚合器接收全部相关数据；需要水平拆分时，应使用-remoteWrite.shardByURL.labels/-remoteWrite.shardByURL.ignoreLabels确定性分片，并保证分片配置与by/without对齐（by中的标签须为分片标签的超集，without中的标签须被分片忽略），同时为各聚合实例打唯一标签避免输出冲突。
2. 不要为每条 recording rule 各建一个聚合器：每个聚合规则都会让输入流逐条匹配，规则过多会抬升资源占用。应把仅match不同的聚合合并，例如把 3 条node_*的 rate 求和 recording rule 合并为一条多match的rate_sum聚合。
3. 多个-remoteWrite.url不要各自配置一份相同内容的-remoteWrite.streamAggr.config：每个配置会在数据流的副本上独立执行，应改用全局-streamAggr.config聚合一次再复制。
4. 使用keep_metric_names后要同步更新告警与看板查询：聚合后指标语义通常与原始指标不同。
5. 高资源占用时的调优方向：收紧match过滤、增大interval、用更具体的by或更宽泛的without降低输出序列数、用input_relabel_configs/dropInputLabels提前丢弃无用标签。

九、快速参考：三则可直接上手的配置示例

1. 降低样本频率（降采样），每 5 分钟输出一个样本：

# 对以 _total 结尾的指标用 total 输出 - match: '{__name__=~".+_total"}' interval: 5m outputs: [total] # 其余指标用 count_samples、sum_samples、min、max 降采样 - match: '{__name__!~".+_total"}' interval: 5m outputs: [count_samples, sum_samples, min, max]

2. 降低序列基数：聚合时去掉path、user高基标签：

- match: 'http_requests_total' interval: 30s without: [path, user] outputs: [total]

输出指标名示例：http_requests_total:30s_without_path_user_total。

3. 计算请求时延的分位数与直方图：

- match: - request_duration_seconds - response_size_bytes interval: 30s outputs: ["quantiles(0.50, 0.99)"]

- match: - request_duration_seconds - response_size_bytes interval: 60s outputs: [histogram_bucket]

随后可用histogram_quantiles("quantile", 0.50, 0.99, sum(increase(request_duration_seconds:60s_histogram_bucket[1h])) by (vmrange))等 MetricsQL 查询近一小时的分位数估计。

十、延伸阅读与源码索引

• 流式聚合总览（特性、用例、路由、去重、relabeling、横向扩展、故障排查）：docs/victoriametrics/stream-aggregation/README.md
• 本文对应的配置文档原文：docs/victoriametrics/stream-aggregation/configuration.md
• 核心实现（配置解析、校验、聚合器状态机与 flush 调度）：lib/streamaggr/streamaggr.go
• 聚合输出实现：avg、count_samples、count_series、histogram_bucket、increase、last、max、min、quantiles、rate、std、sum_samples、total、unique_samples等文件均位于 lib/streamaggr
• 去重实现：lib/streamaggr/dedup.go
• vmagent 组件：app/vmagent；单机版组件：app/victoria-metrics
• 关键概念（counter / gauge / histogram / 原始样本）：docs/victoriametrics/keyConcepts/keyConcepts.md

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics