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 文件参数适用组件说明-streamAggr.config单机版 VictoriaMetrics、vmagent全局流式聚合配置入口作用于所有进入的数据-remoteWrite.streamAggr.config仅 vmagent可为每个-remoteWrite.url单独指定聚合针对该远端存储独立进行从而可向不同远端写入不同聚合结果配置文件中支持%{ENV_VAR}占位符运行时会被替换为对应环境变量的值。这一机制与组件其他环境变量展开逻辑一致相关实现可参考 lib/envtemplate/envtemplate.go。原始输入样本的去留控制启用流式聚合后默认写入存储的数据有两类聚合后的样本未匹配任何聚合规则match的原始输入样本。该默认行为可通过以下参数改变-streamAggr.keepInput单机版 / vmagentvmagent 上亦可按-remoteWrite.url单独指定-remoteWrite.streamAggr.keepInput设置后匹配任一规则的输入样本也会被保留并写入存储-streamAggr.dropInput单机版 / vmagentvmagent 上亦可按-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 时每分钟末 flushinterval: 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 查询回看窗口保持一致且不能小于intervalby与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]_outputmetric_name为原始指标名interval为配置中的聚合周期by_labels为by标签的_分隔排序列表未设置by时不出现该段without_labels为without标签的_分隔排序列表未设置时不出现该段output为outputs列表中的聚合函数名。例如foo{appbar,instancehost1}在interval: 1m、outputs: [sum_samples]下输出foo:1m_sum_samples{appbar,instancehost1}若配置without: [instance]则输出foo:1m_without_instance_sum_samples{appbar}若配置by: [app]则输出foo:1m_by_app_sum_samples{appbar}。设置keep_metric_names: true可保留原始指标名但仅限单输出场景。实现上suffix 最终在addMetricSuffixlib/streamaggr/streamaggr.go中追加到__name__标签上若标签中缺失__name__则自动补建。四、配置热加载两种方式无需重启进程单机版 VictoriaMetrics 与 vmagent 支持以下两种方式热加载-streamAggr.config/-remoteWrite.streamAggr.config配置向进程发送SIGHUP信号kill -SIGHUP pidof vmagent发送 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输出函数适用指标等价 MetricsQL 表达式avggaugesum(sum_over_time(some_metric[interval])) / sum(count_over_time(some_metric[interval]))count_samples任意sum(count_over_time(some_metric[interval]))count_series任意count(last_over_time(some_metric[interval]))histogram_bucketgaugesum(histogram_over_time(some_histogram_bucket[interval])) by (vmrange)increasecountersum(increase_pure(some_counter[interval]))increase_prometheuscountersum(increase_prometheus(some_counter[interval]))last任意last_over_time(some_metric[interval])max任意max(max_over_time(some_metric[interval]))min任意min(min_over_time(some_metric[interval]))rate_avgcounteravg(rate(some_counter[interval]))rate_sumcountersum(rate(some_counter[interval]))stddevgaugehistogram_stddev(sum(histogram_over_time(some_metric[interval])) by (vmrange))stdvargaugehistogram_stdvar(sum(histogram_over_time(some_metric[interval])) by (vmrange))sum_samplesgaugesum(sum_over_time(some_metric[interval]))sum_samples_totaldelta 值如 StatsD countersum(running_sum(some_delta_values))totalcountersum(running_sum(increase_pure(some_counter)))total_prometheuscountersum(running_sum(increase_prometheus(some_counter)))unique_samplesgaugecount(count_values_over_time(some_metric[interval]))quantiles(phi1, ..., phiN)gaugehistogram_quantiles(quantile, phi1, ..., phiN, sum(histogram_over_time(some_metric[interval])) by (vmrange))下面按类别详解各函数的行为要点含源码级实现依据。5.1 计数与求和类count_samples / count_series / sum_samples / unique_samples / sum_samples_totalcount_samples统计给定interval内接收到的输入样本条数。典型用途是事件计数例如广告服务器按请求产生hits{somelabels} 1、clicks{somelabels} 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 / avgmin/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_sumrate_avg返回interval内各输入 counter 每秒增长率的平均。rate_sum返回各输入 counter 每秒增长率的求和。rate_sum是聚合直方图histogram bucket 系列的标准做法直方图是一组带le或vmrange标签的 counter对它们整体做rate_sum后可配合histogram_quantile计算分位数。实现细节参见 lib/streamaggr/rate.go其中每个序列记录prevTimestamp与当前区间累计 increaseflush 时按increase / (timestamp - prevTimestamp)折算每秒速率。5.5 分布类stddev / stdvar / histogram_bucket / quantilesstddev/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单机版 / vmagentvmagent 可逐-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.dedupInterval30s对所有数据或-remoteWrite.streamAggr.dedupInterval30s对特定-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 生命周期文档典型路由场景聚合后复制到 N 个远端使用全局-streamAggr.config聚合一次后复制到所有-remoteWrite.url为每个远端独立聚合为每个-remoteWrite.url分别指定-remoteWrite.streamAggr.config配合-remoteWrite.urlRelabelConfig将选定指标路由到不同远端。流式聚合还支持两级 relabelinginput_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.dropInputLabelsreplica,az、按远端-remoteWrite.streamAggr.dropInputLabels多个标签用^^分隔、以及配置内drop_input_labels优先级最高先于 input relabeling 与去重执行。八、运维最佳实践与常见误区结合 README.md 的 Troubleshooting 部分以下实践值得牢记把聚合器放在负载均衡之后是错误的聚合正确性依赖同一聚合器接收全部相关数据需要水平拆分时应使用-remoteWrite.shardByURL.labels/-remoteWrite.shardByURL.ignoreLabels确定性分片并保证分片配置与by/without对齐by中的标签须为分片标签的超集without中的标签须被分片忽略同时为各聚合实例打唯一标签避免输出冲突。不要为每条 recording rule 各建一个聚合器每个聚合规则都会让输入流逐条匹配规则过多会抬升资源占用。应把仅match不同的聚合合并例如把 3 条node_*的 rate 求和 recording rule 合并为一条多match的rate_sum聚合。多个-remoteWrite.url不要各自配置一份相同内容的-remoteWrite.streamAggr.config每个配置会在数据流的副本上独立执行应改用全局-streamAggr.config聚合一次再复制。使用keep_metric_names后要同步更新告警与看板查询聚合后指标语义通常与原始指标不同。高资源占用时的调优方向收紧match过滤、增大interval、用更具体的by或更宽泛的without降低输出序列数、用input_relabel_configs/dropInputLabels提前丢弃无用标签。九、快速参考三则可直接上手的配置示例降低样本频率降采样每 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]降低序列基数聚合时去掉path、user高基标签- match: http_requests_total interval: 30s without: [path, user] outputs: [total]输出指标名示例http_requests_total:30s_without_path_user_total。计算请求时延的分位数与直方图- 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.govmagent 组件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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
VictoriaMetrics 流式聚合配置指南：streamAggr 配置格式、聚合函数与热加载实战
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 文件参数适用组件说明-streamAggr.config单机版 VictoriaMetrics、vmagent全局流式聚合配置入口作用于所有进入的数据-remoteWrite.streamAggr.config仅 vmagent可为每个-remoteWrite.url单独指定聚合针对该远端存储独立进行从而可向不同远端写入不同聚合结果配置文件中支持%{ENV_VAR}占位符运行时会被替换为对应环境变量的值。这一机制与组件其他环境变量展开逻辑一致相关实现可参考 lib/envtemplate/envtemplate.go。原始输入样本的去留控制启用流式聚合后默认写入存储的数据有两类聚合后的样本未匹配任何聚合规则match的原始输入样本。该默认行为可通过以下参数改变-streamAggr.keepInput单机版 / vmagentvmagent 上亦可按-remoteWrite.url单独指定-remoteWrite.streamAggr.keepInput设置后匹配任一规则的输入样本也会被保留并写入存储-streamAggr.dropInput单机版 / vmagentvmagent 上亦可按-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 时每分钟末 flushinterval: 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 查询回看窗口保持一致且不能小于intervalby与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]_outputmetric_name为原始指标名interval为配置中的聚合周期by_labels为by标签的_分隔排序列表未设置by时不出现该段without_labels为without标签的_分隔排序列表未设置时不出现该段output为outputs列表中的聚合函数名。例如foo{appbar,instancehost1}在interval: 1m、outputs: [sum_samples]下输出foo:1m_sum_samples{appbar,instancehost1}若配置without: [instance]则输出foo:1m_without_instance_sum_samples{appbar}若配置by: [app]则输出foo:1m_by_app_sum_samples{appbar}。设置keep_metric_names: true可保留原始指标名但仅限单输出场景。实现上suffix 最终在addMetricSuffixlib/streamaggr/streamaggr.go中追加到__name__标签上若标签中缺失__name__则自动补建。四、配置热加载两种方式无需重启进程单机版 VictoriaMetrics 与 vmagent 支持以下两种方式热加载-streamAggr.config/-remoteWrite.streamAggr.config配置向进程发送SIGHUP信号kill -SIGHUP pidof vmagent发送 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输出函数适用指标等价 MetricsQL 表达式avggaugesum(sum_over_time(some_metric[interval])) / sum(count_over_time(some_metric[interval]))count_samples任意sum(count_over_time(some_metric[interval]))count_series任意count(last_over_time(some_metric[interval]))histogram_bucketgaugesum(histogram_over_time(some_histogram_bucket[interval])) by (vmrange)increasecountersum(increase_pure(some_counter[interval]))increase_prometheuscountersum(increase_prometheus(some_counter[interval]))last任意last_over_time(some_metric[interval])max任意max(max_over_time(some_metric[interval]))min任意min(min_over_time(some_metric[interval]))rate_avgcounteravg(rate(some_counter[interval]))rate_sumcountersum(rate(some_counter[interval]))stddevgaugehistogram_stddev(sum(histogram_over_time(some_metric[interval])) by (vmrange))stdvargaugehistogram_stdvar(sum(histogram_over_time(some_metric[interval])) by (vmrange))sum_samplesgaugesum(sum_over_time(some_metric[interval]))sum_samples_totaldelta 值如 StatsD countersum(running_sum(some_delta_values))totalcountersum(running_sum(increase_pure(some_counter)))total_prometheuscountersum(running_sum(increase_prometheus(some_counter)))unique_samplesgaugecount(count_values_over_time(some_metric[interval]))quantiles(phi1, ..., phiN)gaugehistogram_quantiles(quantile, phi1, ..., phiN, sum(histogram_over_time(some_metric[interval])) by (vmrange))下面按类别详解各函数的行为要点含源码级实现依据。5.1 计数与求和类count_samples / count_series / sum_samples / unique_samples / sum_samples_totalcount_samples统计给定interval内接收到的输入样本条数。典型用途是事件计数例如广告服务器按请求产生hits{somelabels} 1、clicks{somelabels} 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 / avgmin/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_sumrate_avg返回interval内各输入 counter 每秒增长率的平均。rate_sum返回各输入 counter 每秒增长率的求和。rate_sum是聚合直方图histogram bucket 系列的标准做法直方图是一组带le或vmrange标签的 counter对它们整体做rate_sum后可配合histogram_quantile计算分位数。实现细节参见 lib/streamaggr/rate.go其中每个序列记录prevTimestamp与当前区间累计 increaseflush 时按increase / (timestamp - prevTimestamp)折算每秒速率。5.5 分布类stddev / stdvar / histogram_bucket / quantilesstddev/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单机版 / vmagentvmagent 可逐-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.dedupInterval30s对所有数据或-remoteWrite.streamAggr.dedupInterval30s对特定-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 生命周期文档典型路由场景聚合后复制到 N 个远端使用全局-streamAggr.config聚合一次后复制到所有-remoteWrite.url为每个远端独立聚合为每个-remoteWrite.url分别指定-remoteWrite.streamAggr.config配合-remoteWrite.urlRelabelConfig将选定指标路由到不同远端。流式聚合还支持两级 relabelinginput_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.dropInputLabelsreplica,az、按远端-remoteWrite.streamAggr.dropInputLabels多个标签用^^分隔、以及配置内drop_input_labels优先级最高先于 input relabeling 与去重执行。八、运维最佳实践与常见误区结合 README.md 的 Troubleshooting 部分以下实践值得牢记把聚合器放在负载均衡之后是错误的聚合正确性依赖同一聚合器接收全部相关数据需要水平拆分时应使用-remoteWrite.shardByURL.labels/-remoteWrite.shardByURL.ignoreLabels确定性分片并保证分片配置与by/without对齐by中的标签须为分片标签的超集without中的标签须被分片忽略同时为各聚合实例打唯一标签避免输出冲突。不要为每条 recording rule 各建一个聚合器每个聚合规则都会让输入流逐条匹配规则过多会抬升资源占用。应把仅match不同的聚合合并例如把 3 条node_*的 rate 求和 recording rule 合并为一条多match的rate_sum聚合。多个-remoteWrite.url不要各自配置一份相同内容的-remoteWrite.streamAggr.config每个配置会在数据流的副本上独立执行应改用全局-streamAggr.config聚合一次再复制。使用keep_metric_names后要同步更新告警与看板查询聚合后指标语义通常与原始指标不同。高资源占用时的调优方向收紧match过滤、增大interval、用更具体的by或更宽泛的without降低输出序列数、用input_relabel_configs/dropInputLabels提前丢弃无用标签。九、快速参考三则可直接上手的配置示例降低样本频率降采样每 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]降低序列基数聚合时去掉path、user高基标签- match: http_requests_total interval: 30s without: [path, user] outputs: [total]输出指标名示例http_requests_total:30s_without_path_user_total。计算请求时延的分位数与直方图- 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.govmagent 组件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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
