docs: stream aggregation updated structure, added common mistakes section

2024-11-21 14:44:00 +00:00 · 2024-08-10 08:12:38 +03:00 · 2024-08-10 08:12:38 +03:00 · b8f06e9636
commit b8f06e9636
parent cb00b4b00f
25 changed files with 1499 additions and 1248 deletions
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@ -73,7 +73,7 @@ The v1.102.x line will be supported for at least 12 months since [v1.102.0](http
 **Update note 1: support for snap packages was removed due to lack of interest from community. See this [pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/6543) for details. Please read about supported package types [here](https://docs.victoriametrics.com/#install).**
-**Update note 2: [stream aggregation config](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config) now prevents setting multiple identical outputs. For example, `outputs: [total, total]` will fail the validation phase. In addition, `outputs: ["quantiles(0.5)", "quantiles(0.9)"]` will fail the validation as well - use `outputs: ["quantiles(0.5, 0.9)"]` instead.**
+**Update note 2: [stream aggregation config](https://docs.victoriametrics.com/stream-aggregation/configuration) now prevents setting multiple identical outputs. For example, `outputs: [total, total]` will fail the validation phase. In addition, `outputs: ["quantiles(0.5)", "quantiles(0.9)"]` will fail the validation as well - use `outputs: ["quantiles(0.5, 0.9)"]` instead.**
 * SECURITY: upgrade Go builder from Go1.22.4 to Go1.22.5. See the list of issues addressed in [Go1.22.5](https://github.com/golang/go/issues?q=milestone%3AGo1.22.5+label%3ACherryPickApproved).
 * SECURITY: upgrade base docker image (Alpine) from 3.20.0 to 3.20.1. See [alpine 3.20.1 release notes](https://www.alpinelinux.org/posts/Alpine-3.20.1-released.html).
@ -83,11 +83,11 @@ The v1.102.x line will be supported for at least 12 months since [v1.102.0](http
  * `vm_streamaggr_output_samples_total` - the number of output samples produced by the corresponding aggregation rule
  * `vm_streamaggr_samples_lag_seconds` - [histogram](https://docs.victoriametrics.com/keyconcepts/#histogram) with the lag between the current time and the timestamp seen in the aggregated input samples
 * FEATURE: [steaming aggregation](https://docs.victoriametrics.com/stream-aggregation/): add new labels to `vm_streamaggr_*` metrics:
-  * `name` - the name of the streaming aggregation rule, which can be configured via `name` option - see [these docs](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config).
+  * `name` - the name of the streaming aggregation rule, which can be configured via `name` option - see [these docs](https://docs.victoriametrics.com/stream-aggregation/configuration/).
  * `url` - `-remoteWrite.url` for the corresponding `-remoteWrite.streamAggr.config`
  * `path` - path to the corresponding streaming aggregation config file
  * `position` - the position of the aggregation rule in the corresponding streaming aggregation config file
-* FEATURE: [streaming aggregation](https://docs.victoriametrics.com/stream-aggregation/): prevent having duplicated aggregation function as `outputs` in one [aggregation config](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config). It also prevents using `outputs: ["quantiles(0.5)", "quantiles(0.9)"]` instead of  `outputs: ["quantiles(0.5, 0.9)"]`, as the former has higher computation cost for producing the same result.
+* FEATURE: [streaming aggregation](https://docs.victoriametrics.com/stream-aggregation/): prevent having duplicated aggregation function as `outputs` in one [aggregation config](https://docs.victoriametrics.com/stream-aggregation/configuration/). It also prevents using `outputs: ["quantiles(0.5)", "quantiles(0.9)"]` instead of  `outputs: ["quantiles(0.5, 0.9)"]`, as the former has higher computation cost for producing the same result.
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/) and [Single-node VictoriaMetrics](https://docs.victoriametrics.com/): add `-graphite.sanitizeMetricName` command-line flag for sanitizing metrics ingested via [Graphite protocol](https://docs.victoriametrics.com/#how-to-send-data-from-graphite-compatible-agents-such-as-statsd). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6077).
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): [`yandexcloud_sd_configs`](https://docs.victoriametrics.com/sd_configs/#yandexcloud_sd_configs): add support for obtaining IAM token in [GCE format](https://yandex.cloud/en-ru/docs/compute/operations/vm-connect/auth-inside-vm#auth-inside-vm) additionally to the [deprecated Amazon EC2 IMDSv1 format](https://yandex.cloud/en/docs/security/standard/authentication#aws-token). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/5513).
 * FEATURE: [vmalert](https://docs.victoriametrics.com/vmalert/): make `-replay.timeTo` optional in [replay mode](https://docs.victoriametrics.com/vmalert/#rules-backfilling). When omitted, the current timestamp will be used. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6492).
@ -131,7 +131,7 @@ Released at 2024-06-24
 * BUGFIX: all VictoriaMetrics components: prioritize `-configAuthKey` and `-reloadAuthKey` over `-httpAuth.*` settings. This change aligns behavior of mentioned flags with other auth flags like `-metricsAuthKey`, `-flagsAuthKey`, `-pprofAuthKey`. Check [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6329).
 * BUGFIX: all VictoriaMetrics components: do not trim trailing spaces when reading content from `*.passwordFile` and similar flags. Previously, trailing spaces were trimmed from the content of the password file, which could lead to unexpected authentication errors.
 * BUGFIX: [vmctl](https://docs.victoriametrics.com/vmctl/): add `--disable-progress-bar` global command-line flag. It can be used for disabling dynamic progress bar for all migration modes. `--vm-disable-progress-bar`  command-line flag is deprecated and will be removed in the future releases. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6367).
-* BUGFIX: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): prevent [rate_sum](https://docs.victoriametrics.com/stream-aggregation/#rate_sum) and [rate_avg](https://docs.victoriametrics.com/stream-aggregation/#rate_avg) producing `NaN` results for stale time series. Before, when series matched for aggregation became stale or weren't updated during aggregation interval, the `rate_sum` or `rate_avg` could produce data point with `NaN` value. During visualization, such aggregation results would be displayed as gaps in time series.
+* BUGFIX: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): prevent [rate_sum](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#rate_sum) and [rate_avg](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#rate_avg) producing `NaN` results for stale time series. Before, when series matched for aggregation became stale or weren't updated during aggregation interval, the `rate_sum` or `rate_avg` could produce data point with `NaN` value. During visualization, such aggregation results would be displayed as gaps in time series.
 * BUGFIX: [vmalert](https://docs.victoriametrics.com/vmalert/): fix path for system links printed on default vmalert's UI page when `-http.pathPrefix` is set. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6433).
 * BUGFIX: [vmalert](https://docs.victoriametrics.com/vmalert/): exit replay mode with non-zero code if generated samples are not successfully written into remoteWrite url. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6512).
 * BUGFIX: [vmbackup](https://docs.victoriametrics.com/vmbackup/): properly configure authentication with S3 when `-configFilePath` cmd-line flag is specified. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6353).
@ -166,7 +166,7 @@ Released at 2024-06-07
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): add service discovery support for [Vultr](https://www.vultr.com/). See [these docs](https://docs.victoriametrics.com/sd_configs/#vultr_sd_configs) and [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6041).
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): allow specifying `-remoteWrite.disableOnDiskQueue` command-line flag per each `-remoteWrite.url`. If multiple `-remoteWrite.disableOnDiskQueue` command-line flags are configured, then the `-remoteWrite.dropSamplesOnOverload` is automatically set to true, so samples are automatically dropped if they cannot be sent to the corresponding `-remoteWrite.url` in a timely manner. See this [pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/6065). Thanks to @rbizos for implementation!
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): add `path` and `url` labels to `vmagent_remotewrite_push_failures_total` and `vmagent_remotewrite_samples_dropped_total` [metrics](https://docs.victoriametrics.com/vmagent/#monitoring), so the number of failed pushes and dropped samples can be tracked per each `-remoteWrite.url`.
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add [rate_sum](https://docs.victoriametrics.com/stream-aggregation/#rate_sum) and [rate_avg](https://docs.victoriametrics.com/stream-aggregation/#rate_avg) aggregation outputs.
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add [rate_sum](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#rate_sum) and [rate_avg](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#rate_avg) aggregation outputs.
 * FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): reduce the number of allocated objects in heap during deduplication and aggregation. The change supposed to reduce pressure on Garbage Collector, as it will need to scan less objects. See [this pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/6402).
 * FEATURE: [vmalert](https://docs.victoriametrics.com/vmalert/): add `-datasource.idleConnTimeout`, `-remoteWrite.idleConnTimeout` and `-remoteRead.idleConnTimeout` flags. These flags are set to 50s by default and should reduce the probability of `broken pipe` or `connection reset by peer` errors in vmalert logs. See this [issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/5661) for details.
 * FEATURE: [vmalert](https://docs.victoriametrics.com/vmalert/): add auto request retry for trivial network errors, such as `broken pipe` and `connection reset` for requests to `remoteRead`, `remoteWrite` and `datasource` URLs. See this [issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/5661) for details.
@ -177,16 +177,16 @@ Released at 2024-06-07
 * FEATURE: expose metric `vm_indexdb_items_dropped_total` to track the number of IndexDB records that had to be dropped during ingestion. The reason of dropping the record will be annotated in `reason` label of the exposed metric. This change also comes with a new [alerting rule](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/deployment/docker/alerts-health.yml) to track changes of this metric.
 * FEATURE: [alerts-health](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/deployment/docker/alerts-health.yml): add new alerting rules `TooLongLabelValues` and `TooLongLabelNames` to notify about truncation of label values or names respectively.
 * FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): expose `vm_streamaggr_ignored_samples_total` [counters](https://docs.victoriametrics.com/keyconcepts/#counter) at [`/metrics` page](https://docs.victoriametrics.com/#monitoring), which can be used for detecting amount of too old or NaN valued ignored samples. Expose also `vm_streamaggr_samples_lag_seconds` [histogram](https://docs.victoriametrics.com/keyconcepts/#histogram) to monitor aggregated samples lag.
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): improve filtering speed of the received data samples if [match](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config) field is matching only [metric name](https://docs.victoriametrics.com/keyconcepts/#structure-of-a-metric).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): improve filtering speed of the received data samples if [match](https://docs.victoriametrics.com/stream-aggregation/configuration) field is matching only [metric name](https://docs.victoriametrics.com/keyconcepts/#structure-of-a-metric).
 * FEATURE: [VictoriaMetrics cluster](https://docs.victoriametrics.com/cluster-victoriametrics/): adds `-relabelConfigCheckInterval` flag and `/-/reload` endpoint for reloading relabeling rules. See this [pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/3923) for details.
 * BUGFIX: [vmui](https://docs.victoriametrics.com/#vmui): fix bug that prevents the first query trace from expanding on click event. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6186). The issue was introduced in [v1.100.0](https://docs.victoriametrics.com/changelog/#v11000) release.
 * BUGFIX: [vmui](https://docs.victoriametrics.com/#vmui): fix calendar display when `UTC+00:00` timezone is set. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6239).
 * BUGFIX: [vmui](https://docs.victoriametrics.com/#vmui): remove redundant requests on the `Explore Cardinality` page. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6240).
 * BUGFIX: [vmui](https://docs.victoriametrics.com/#vmui): fix handling of URL params for browser history navigation (back and forward buttons). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6126) and [this comment](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/5516#issuecomment-1867507232).
-* BUGFIX: [vmagent](https://docs.victoriametrics.com/vmagent/): prevent potential panic during [stream aggregation](https://docs.victoriametrics.com/stream-aggregation.html) when more than one `-remoteWrite.url` command-line flags are passed to `vmagent` together with non-zero `-remoteWrite.streamAggr.dedupInterval` command-line flag. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6205).
+* BUGFIX: [vmagent](https://docs.victoriametrics.com/vmagent/): prevent potential panic during [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/) when more than one `-remoteWrite.url` command-line flags are passed to `vmagent` together with non-zero `-remoteWrite.streamAggr.dedupInterval` command-line flag. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6205).
 * BUGFIX: [vmagent](https://docs.victoriametrics.com/vmagent/): skip empty data blocks before sending to the remote write destination. Thanks to @viperstars for [the pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/6241).
-* BUGFIX: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): set correct suffix `<output>_prometheus` for aggregation outputs [increase_prometheus](https://docs.victoriametrics.com/stream-aggregation/#increase_prometheus) and [total_prometheus](https://docs.victoriametrics.com/stream-aggregation/#total_prometheus). Before, outputs `total` and `total_prometheus` or `increase` and `increase_prometheus` had the same suffix.
+* BUGFIX: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): set correct suffix `<output>_prometheus` for aggregation outputs [increase_prometheus](https://docs.victoriametrics.com/stream-aggregation/configuration/output#increase_prometheus) and [total_prometheus](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#total_prometheus). Before, outputs `total` and `total_prometheus` or `increase` and `increase_prometheus` had the same suffix.
 * BUGFIX: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): prevent from excessive resource usage when stream aggregation config file is empty.
 * BUGFIX: properly estimate the needed memory for query execution if it has the format [`aggr_func`](https://docs.victoriametrics.com/metricsql/#aggregate-functions)([`rollup_func[d]`](https://docs.victoriametrics.com/metricsql/#rollup-functions) (for example, `sum(rate(request_duration_seconds_bucket[5m]))`). This should allow performing aggregations over bigger number of time series when VictoriaMetrics runs in environments with small amounts of available memory. The issue has been introduced in [this commit](https://github.com/VictoriaMetrics/VictoriaMetrics/commit/5138eaeea0791caa34bcfab410e0ca9cd253cd8f) in [v1.83.0](https://docs.victoriametrics.com/changelog_2022/#v1830).
 * BUGFIX: [Single-node VictoriaMetrics](https://docs.victoriametrics.com/) and `vmstorage` in [VictoriaMetrics cluster](https://docs.victoriametrics.com/cluster-victoriametrics/): correctly apply `-inmemoryDataFlushInterval` when it's set to minimum supported value 1s.
@ -212,7 +212,7 @@ Released at 2024-04-26
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): reduce CPU usage when [sharding among remote storage systems](https://docs.victoriametrics.com/vmagent/#sharding-among-remote-storages) is enabled.
 * FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): reduce memory usage during stream aggregation if multiple aggregation configs are used for the same set of data.
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): support [DNS SRV](https://en.wikipedia.org/wiki/SRV_record) addresses in `-remoteWrite.url` command-line option and in scrape target urls. For example, `-remoteWrite.url=http://srv+victoria-metrics/api/v1/write` automatically resolves the `victoria-metrics` DNS SRV to a list of hostnames with TCP ports and then sends the collected metrics to these TCP addresses. See [these docs](https://docs.victoriametrics.com/vmagent/#srv-urls) and [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6053).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): allow skipping first N aggregation intervals via cmd-line flag `-streamAggr.ignoreFirstIntervals` for [Single-node VictoriaMetrics](https://docs.victoriametrics.com/) or `-remoteWrite.streamAggr.ignoreFirstIntervals` for [vmagent](https://docs.victoriametrics.com/vmagent/). See more details [here](https://docs.victoriametrics.com/stream-aggregation/#ignore-aggregation-intervals-on-start).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): allow skipping first N aggregation intervals via cmd-line flag `-streamAggr.ignoreFirstIntervals` for [Single-node VictoriaMetrics](https://docs.victoriametrics.com/) or `-remoteWrite.streamAggr.ignoreFirstIntervals` for [vmagent](https://docs.victoriametrics.com/vmagent/). See more details [here](https://docs.victoriametrics.com/stream-aggregation/key-concepts#ignore-aggregation-intervals-on-start).
 * FEATURE: [vmauth](https://docs.victoriametrics.com/vmauth/): support automatic discovering and load balancing for TCP addresses behind DNS SRV addresses. These addresses can be put inside `url_prefix` urls in the form `http://srv+addr/path`, where the `addr` is the [DNS SRV](https://en.wikipedia.org/wiki/SRV_record) address, which is automatically resolved to hostnames with TCP ports. See [these docs](https://docs.victoriametrics.com/vmauth/#srv-urls) for details.
 * FEATURE: [vmauth](https://docs.victoriametrics.com/vmauth/): support specifying client TLS certificates and TLS ServerName for requests to HTTPS backends. See [these docs](https://docs.victoriametrics.com/vmauth/#backend-tls-setup).
 * FEATURE: [vmauth](https://docs.victoriametrics.com/vmauth/): support regex matching when routing incoming requests based on HTTP [query args](https://en.wikipedia.org/wiki/Query_string) via `src_query_args` option at `url_map`. See [these docs](https://docs.victoriametrics.com/vmauth/#generic-http-proxy-for-different-backends) and [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/6070).
@ -257,17 +257,17 @@ Released at 2024-04-04
 * FEATURE: [vmauth](https://docs.victoriametrics.com/vmauth/): allow routing incoming requests based on HTTP request headers via `src_headers` option at `url_map`. See [these docs](https://docs.victoriametrics.com/vmauth/#generic-http-proxy-for-different-backends).
 * FEATURE: [vmauth](https://docs.victoriametrics.com/vmauth/): add ability to read auth tokens from arbitrary HTTP request headers via `-httpAuthHeader` command-line flag. Previously auth tokens were read only from `Authorization` HTTP request header. See [these docs](https://docs.victoriametrics.com/vmauth/#reading-auth-tokens-from-other-http-headers) for details.
 * FEATURE: [vmauth](https://docs.victoriametrics.com/vmauth/): add ability to authorize by opaque HTTP request header value via `auth_token` option in [-auth.config](https://docs.victoriametrics.com/vmauth/#auth-config).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): reduce memory usage by up to 5x when aggregating over big number of unique [time series](https://docs.victoriametrics.com/keyconcepts/#time-series). The memory usage reduction is most visible when [stream deduplication](https://docs.victoriametrics.com/stream-aggregation/#deduplication) is enabled.
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): reduce memory usage by up to 5x when aggregating over big number of unique [time series](https://docs.victoriametrics.com/keyconcepts/#time-series). The memory usage reduction is most visible when [stream deduplication](https://docs.victoriametrics.com/stream-aggregation/key-concepts#deduplication) is enabled.
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): allow using `-streamAggr.dedupInterval` and `-remoteWrite.streamAggr.dedupInterval` command-line flags without the need to specify `-streamAggr.config` and `-remoteWrite.streamAggr.config`. See [these docs](https://docs.victoriametrics.com/stream-aggregation/#deduplication).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): allow using `-streamAggr.dedupInterval` and `-remoteWrite.streamAggr.dedupInterval` command-line flags without the need to specify `-streamAggr.config` and `-remoteWrite.streamAggr.config`. See [these docs](https://docs.victoriametrics.com/stream-aggregation/key-concepts#deduplication).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add `-streamAggr.dropInputLabels` command-line flag, which can be used for dropping the listed labels from input samples before applying stream [de-duplication](https://docs.victoriametrics.com/stream-aggregation/#deduplication) and aggregation. This is faster and easier to use alternative to [input_relabel_configs](https://docs.victoriametrics.com/stream-aggregation/#relabeling). See [these docs](https://docs.victoriametrics.com/stream-aggregation/#dropping-unneeded-labels).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add `-streamAggr.dropInputLabels` command-line flag, which can be used for dropping the listed labels from input samples before applying stream [de-duplication](https://docs.victoriametrics.com/stream-aggregation/key-concepts#deduplication) and aggregation. This is faster and easier to use alternative to [input_relabel_configs](https://docs.victoriametrics.com/stream-aggregation/key-concepts#relabeling). See [these docs](https://docs.victoriametrics.com/stream-aggregation/key-concepts#dropping-unneeded-labels).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add `dedup_interval` option, which allows configuring individual [deduplication intervals](https://docs.victoriametrics.com/stream-aggregation/#deduplication) per each [stream aggregation config](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add `dedup_interval` option, which allows configuring individual [deduplication intervals](https://docs.victoriametrics.com/stream-aggregation/key-concepts#deduplication) per each [stream aggregation config](https://docs.victoriametrics.com/stream-aggregation/configuration).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): use the same logic in [stream deduplication](https://docs.victoriametrics.com/stream-aggregation/#deduplication) as in [the deduplication at VictoriaMetrics](https://docs.victoriametrics.com/#deduplication). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/5643).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): use the same logic in [stream deduplication](https://docs.victoriametrics.com/stream-aggregation/key-concepts#deduplication) as in [the deduplication at VictoriaMetrics](https://docs.victoriametrics.com/#deduplication). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/5643).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): ignore out of order samples when calculating [`increase`](https://docs.victoriametrics.com/stream-aggregation/#increase), [`increase_prometheus`](https://docs.victoriametrics.com/stream-aggregation/#increase_prometheus), [`total`](https://docs.victoriametrics.com/stream-aggregation/#total) and [`total_prometheus`](https://docs.victoriametrics.com/stream-aggregation/#total_prometheus) outputs. Thanks to @edma2 for [the pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/5931).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): ignore out of order samples when calculating [`increase`](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#increase), [`increase_prometheus`](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#increase_prometheus), [`total`](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#total) and [`total_prometheus`](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#total_prometheus) outputs. Thanks to @edma2 for [the pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/5931).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add an ability to ignore input samples with old timestamps outside the current aggregation interval. See [these docs](https://docs.victoriametrics.com/stream-aggregation/#ignoring-old-samples) for details.
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add an ability to ignore input samples with old timestamps outside the current aggregation interval. See [these docs](https://docs.victoriametrics.com/stream-aggregation/key-concepts#ignoring-old-samples) for details.
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add `keep_metric_names` option, which can be set at [stream aggregation config](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config) in order to keep the original metric names in the output aggregated samples instead of using [the default output metric naming scheme](https://docs.victoriametrics.com/stream-aggregation/#output-metric-names).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add `keep_metric_names` option, which can be set at [stream aggregation config](https://docs.victoriametrics.com/stream-aggregation/configuration) in order to keep the original metric names in the output aggregated samples instead of using [the default output metric naming scheme](https://docs.victoriametrics.com/stream-aggregation/key-concepts#output-metric-names).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): align the time of aggregated data flush to the specified aggregation `interval`. For example, if `interval` is set to `1m`, then the aggregated data will be flushed at the end of every minute. The alignment can be disabled by setting `no_align_flush_to_interval: true` option at [stream aggregation config](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config). See [these docs](https://docs.victoriametrics.com/stream-aggregation/#flush-time-alignment) for details.
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): align the time of aggregated data flush to the specified aggregation `interval`. For example, if `interval` is set to `1m`, then the aggregated data will be flushed at the end of every minute. The alignment can be disabled by setting `no_align_flush_to_interval: true` option at [stream aggregation config](https://docs.victoriametrics.com/stream-aggregation/configuration). See [these docs](https://docs.victoriametrics.com/stream-aggregation/key-concepts#flush-time-alignment) for details.
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add [unique_samples](https://docs.victoriametrics.com/stream-aggregation/#unique_samples) output, which can be used for calculating the number of unique sample values over the given `interval`.
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add [unique_samples](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#unique_samples) output, which can be used for calculating the number of unique sample values over the given `interval`.
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add [increase_prometheus](https://docs.victoriametrics.com/stream-aggregation/#increase_prometheus) and [total_prometheus](https://docs.victoriametrics.com/stream-aggregation/#total_prometheus) outputs, which can be used for `increase` and `total` aggregations when the first sample of every new [time series](https://docs.victoriametrics.com/keyconcepts/#time-series) must be ignored.
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): add [increase_prometheus](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#increase_prometheus) and [total_prometheus](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs#total_prometheus) outputs, which can be used for `increase` and `total` aggregations when the first sample of every new [time series](https://docs.victoriametrics.com/keyconcepts/#time-series) must be ignored.
 * FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): expose `vm_streamaggr_flush_timeouts_total` and `vm_streamaggr_dedup_flush_timeouts_total` [counters](https://docs.victoriametrics.com/keyconcepts/#counter) at [`/metrics` page](https://docs.victoriametrics.com/#monitoring), which can be used for detecting flush timeouts for stream aggregation states. Expose also `vm_streamaggr_flush_duration_seconds` and `vm_streamaggr_dedup_flush_duration_seconds` [histograms](https://docs.victoriametrics.com/keyconcepts/#histogram) for monitoring the real flush durations of stream aggregation states.
 * FEATURE: [vmui](https://docs.victoriametrics.com/#vmui): improve trace display for better visual separation of branches. See [this pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/5926).
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): ability to limit the ingestion rate via `-maxIngestionRate` command-line flag. See [this pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/5900).
@ -512,7 +512,7 @@ The v1.97.x line will be supported for at least 12 months since [v1.97.0](https:
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): reduce initial memory usage when scraping targets, which return huge responses (for example, [kube-state-metrics](https://github.com/kubernetes/kube-state-metrics) in large Kubernetes cluster may return 100MB+ responses), without the need to explicitly enable [stream parsing mode](https://docs.victoriametrics.com/vmagent/#stream-parsing-mode). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/5567).
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): expose ability to set OAuth2 endpoint parameters per each `-remoteWrite.url` via the command-line flag `-remoteWrite.oauth2.endpointParams`. See [these docs](https://docs.victoriametrics.com/vmagent/#advanced-usage). Thanks to @mhill-holoplot for the [pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/5427).
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): add ability to set `attach_metadata.node=true` option for all the [`kubernetes_sd_configs`](https://docs.victoriametrics.com/sd_configs/#kubernetes_sd_configs) defined at [`-promscrape.config`](https://docs.victoriametrics.com/vmagent/#quick-start) via `-promscrape.kubernetes.attachNodeMetadataAll` command-line flag. See [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4640). Thanks to @wasim-nihal for [the initial implementation](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/5593).
-* FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): do not send unfinished [aggregation state](https://docs.victoriametrics.com/stream-aggregation/) on shutdown or [hot config reload](https://docs.victoriametrics.com/stream-aggregation/#configuration-update) by default, as it tend to produce unexpected anomalies with lower values. The old behavior can be restored by specifying `flush_on_shutdown: true` setting in streaming aggregation config. See more details [here](https://docs.victoriametrics.com/stream-aggregation/#aggregation-outputs).
+* FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): do not send unfinished [aggregation state](https://docs.victoriametrics.com/stream-aggregation/) on shutdown or [hot config reload](https://docs.victoriametrics.com/stream-aggregation/configuration#configuration-update) by default, as it tend to produce unexpected anomalies with lower values. The old behavior can be restored by specifying `flush_on_shutdown: true` setting in streaming aggregation config. See more details [here](https://docs.victoriametrics.com/stream-aggregation/configuration/outputs).
 * FEATURE: [streaming aggregation](https://docs.victoriametrics.com/stream-aggregation/): expand `%{ENV_VAR}` placeholders in config files with the corresponding environment variable values.
 * FEATURE: [vmalert](https://docs.victoriametrics.com/vmagent/): expose ability to set OAuth2 endpoint parameters via the following command-line flags:
  * `-datasource.oauth2.endpointParams` for `-datasource.url`
--- a/docs/CHANGELOG_2023.md
+++ b/docs/CHANGELOG_2023.md
@ -331,7 +331,7 @@ The v1.93.x line will be supported for at least 12 months since [v1.93.0](https:
 * BUGFIX: prevent from possible data loss during `indexdb` rotation. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4873) for details.
 * BUGFIX: do not allow starting VictoriaMetrics components with improperly set boolean command-line flags in the form `-boolFlagName value`, since this leads to silent incomplete flags' parsing. This form should be replaced with `-boolFlagName=value`. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4845).
-* BUGFIX: [vmagent](https://docs.victoriametrics.com/vmagent/): properly set labels from `-remoteWrite.label` command-line flag just before sending samples to the configured `-remoteWrite.url` according to [these docs](https://docs.victoriametrics.com/vmagent/#adding-labels-to-metrics). Previously these labels were incorrectly set before [the relabeling](https://docs.victoriametrics.com/vmagent/#relabeling) configured via `-remoteWrite.urlRelabelConfigs` and [the stream aggregation](https://docs.victoriametrics.com/stream-aggregation/) configured via `-remoteWrite.streamAggr.config`, so these labels could be lost or incorrectly transformed before sending the samples to remote storage. The fix allows using `-remoteWrite.label` for identifying `vmagent` instances in [cluster mode](https://docs.victoriametrics.com/vmagent/#scraping-big-number-of-targets). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4247) and [these docs](https://docs.victoriametrics.com/stream-aggregation/#cluster-mode) for more details.
+* BUGFIX: [vmagent](https://docs.victoriametrics.com/vmagent/): properly set labels from `-remoteWrite.label` command-line flag just before sending samples to the configured `-remoteWrite.url` according to [these docs](https://docs.victoriametrics.com/vmagent/#adding-labels-to-metrics). Previously these labels were incorrectly set before [the relabeling](https://docs.victoriametrics.com/vmagent/#relabeling) configured via `-remoteWrite.urlRelabelConfigs` and [the stream aggregation](https://docs.victoriametrics.com/stream-aggregation/) configured via `-remoteWrite.streamAggr.config`, so these labels could be lost or incorrectly transformed before sending the samples to remote storage. The fix allows using `-remoteWrite.label` for identifying `vmagent` instances in [cluster mode](https://docs.victoriametrics.com/vmagent/#scraping-big-number-of-targets). See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4247) and [these docs](https://docs.victoriametrics.com/stream-aggregation/troubleshooting#cluster-mode) for more details.
 * BUGFIX: remove `DEBUG` logging when parsing `if` filters inside [relabeling rules](https://docs.victoriametrics.com/vmagent/#relabeling-enhancements) and when parsing `match` filters inside [stream aggregation rules](https://docs.victoriametrics.com/stream-aggregation/).
 * BUGFIX: properly replace `:` chars in label names with `_` when `-usePromCompatibleNaming` command-line flag is passed to `vmagent`, `vminsert` or single-node VictoriaMetrics. This addresses [this comment](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/3113#issuecomment-1275077071).
 * BUGFIX: [vmbackup](https://docs.victoriametrics.com/vmbackup/): correctly check if specified `-dst` belongs to specified `-storageDataPath`. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4837).
@ -395,7 +395,7 @@ so rolling back to the previous versions of VictoriaMetrics may result in partia
 the following samples to the configured remote storage by default:
 - aggregated samples;
- the original input samples, which match zero `match` options from the provided [config](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config).
+- the original input samples, which match zero `match` options from the provided [config](https://docs.victoriametrics.com/stream-aggregation/configuration).
 Previously only aggregated samples were written to the storage by default.
 The previous behavior can be restored in the following ways:
@ -422,8 +422,8 @@ The previous behavior can be restored in the following ways:
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): allow sharding outgoing time series among the configured remote storage systems. This can be useful for building horizontally scalable [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/), when samples for the same time series must be aggregated by the same `vmagent` instance at the second level. See [these docs](https://docs.victoriametrics.com/vmagent/#sharding-among-remote-storages) and [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4637) for details.
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): allow configuring staleness interval in [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/) config. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4667) for details.
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): allow specifying a list of [series selectors](https://docs.victoriametrics.com/keyconcepts/#filtering) inside `if` option of relabeling rules. The corresponding relabeling rule is executed when at least a single series selector matches. See [these docs](https://docs.victoriametrics.com/vmagent/#relabeling-enhancements).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): allow specifying a list of [series selectors](https://docs.victoriametrics.com/keyconcepts/#filtering) inside `match` option of [stream aggregation configs](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config). The input sample is aggregated when at least a single series selector matches. See [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4635).
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): allow specifying a list of [series selectors](https://docs.victoriametrics.com/keyconcepts/#filtering) inside `match` option of [stream aggregation configs](https://docs.victoriametrics.com/stream-aggregation/configuration). The input sample is aggregated when at least a single series selector matches. See [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4635).
-* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): preserve input samples, which match zero `match` options from the [configured aggregations](https://docs.victoriametrics.com/stream-aggregation/#stream-aggregation-config). Previously all the input samples were dropped by default, so only the aggregated samples are written to the output storage. The previous behavior can be restored by passing `-streamAggr.dropInput` command-line flag to single-node VictoriaMetrics or by passing `-remoteWrite.streamAggr.dropInput` command-line flag to `vmagent`.
+* FEATURE: [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/): preserve input samples, which match zero `match` options from the [configured aggregations](https://docs.victoriametrics.com/stream-aggregation/configuration). Previously all the input samples were dropped by default, so only the aggregated samples are written to the output storage. The previous behavior can be restored by passing `-streamAggr.dropInput` command-line flag to single-node VictoriaMetrics or by passing `-remoteWrite.streamAggr.dropInput` command-line flag to `vmagent`.
 * FEATURE: [vmctl](https://docs.victoriametrics.com/vmctl/): add verbose output for docker installations or when TTY isn't available. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4081).
 * FEATURE: [vmctl](https://docs.victoriametrics.com/vmctl/): interrupt backoff retries when import process is cancelled. The change makes vmctl more responsive in case of errors during the import. See [this pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/4442).
 * FEATURE: [vmctl](https://docs.victoriametrics.com/vmctl/): update backoff policy on retries to reduce probability of overloading for `source` or `destination` databases. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4402).
@ -587,7 +587,7 @@ created by v1.90.0 or newer versions. The solution is to upgrade to v1.90.0 or n
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): add `-kafka.consumer.topic.concurrency` command-line flag. It controls the number of Kafka consumer workers to use by `vmagent`. It should eliminate the need to start multiple `vmagent` instances to improve data transfer rate. See [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/1957).
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): add support for [Kafka producer and consumer](https://docs.victoriametrics.com/vmagent/#kafka-integration) on `arm64` machines. See [this issue](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/2271).
 * FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): delete unused buffered data at `-remoteWrite.tmpDataPath` directory when there is no matching `-remoteWrite.url` to send this data to. See [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/4014).
-* FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): add the ability for hot reloading of [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/) configs. See [these docs](https://docs.victoriametrics.com/stream-aggregation/#configuration-update) and [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/3969).
+* FEATURE: [vmagent](https://docs.victoriametrics.com/vmagent/): add the ability for hot reloading of [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/) configs. See [these docs](https://docs.victoriametrics.com/stream-aggregation/configuration#configuration-update) and [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/3969).
 * FEATURE: check the contents of `-relabelConfig` and `-streamAggr.config` files additionally to `-promscrape.config` when single-node VictoriaMetrics runs with `-dryRun` command-line flag. This aligns the behaviour of single-node VictoriaMetrics with [vmagent](https://docs.victoriametrics.com/vmagent/) behaviour for `-dryRun` command-line flag.
 * FEATURE: [vmui](https://docs.victoriametrics.com/#vmui): automatically draw a heatmap graph when the query selects a single [histogram](https://docs.victoriametrics.com/keyconcepts/#histogram). This simplifies analyzing histograms. See [this feature request](https://github.com/VictoriaMetrics/VictoriaMetrics/issues/3384).
 * FEATURE: [vmui](https://docs.victoriametrics.com/#vmui): add support for drag'n'drop and paste from clipboard in the "Trace analyzer" page. See [this pull request](https://github.com/VictoriaMetrics/VictoriaMetrics/pull/3971).
--- a/docs/guides/getting-started-with-opentelemetry/README.md
+++ b/docs/guides/getting-started-with-opentelemetry/README.md
@ -100,7 +100,7 @@ Metrics could be sent to VictoriaMetrics via OpenTelemetry instrumentation libra
 In our example, we'll create a WEB server in [Golang](https://go.dev/) and instrument it with metrics.
 ### Building the Go application instrumented with metrics
-Copy the go file from [here](/guides/app.go-collector.example). This will give you a basic implementation of a dice roll WEB server with the urls for opentelemetry-collector pointing to localhost:4318. 
+Copy the go file from [here](app.go-collector.example). This will give you a basic implementation of a dice roll WEB server with the urls for opentelemetry-collector pointing to localhost:4318. 
 In the same directory run the following command to create the `go.mod` file:
 ```sh
 go mod init vm/otel
@ -167,7 +167,7 @@ In our example, we'll create a WEB server in [Golang](https://go.dev/) and instr
 ### Building the Go application instrumented with metrics
-See the full source code of the example [here](/guides/app.go.example).
+See the full source code of the example [here](app.go.example).
 The list of OpenTelemetry dependencies for `go.mod` is the following:
@ -314,7 +314,7 @@ func newMetricsController(ctx context.Context) (*controller.Controller, error) {
 This controller will collect and push collected metrics to VictoriaMetrics address with interval of `10s`.
-See the full source code of the example [here](/guides/app.go.example).
+See the full source code of the example [here](app.go.example).
 ### Test metrics ingestion
--- a/docs/guides/k8s-monitoring-via-vm-cluster/vmagent-grafana-dash.webp
+++ b/docs/guides/k8s-monitoring-via-vm-cluster/vmagent-grafana-dash.webp
--- a/docs/guides/migrate-from-influx/data-sample-in-influx.webp
+++ b/docs/guides/migrate-from-influx/data-sample-in-influx.webp
--- a/docs/stream-aggregation.md
+++ b/docs/stream-aggregation.md
--- a/docs/stream-aggregation/README.md
+++ b/docs/stream-aggregation/README.md
@ -0,0 +1,12 @@
 [vmagent](https://docs.victoriametrics.com/vmagent) and [single-node VictoriaMetrics](https://docs.victoriametrics.com)
 can aggregate incoming [samples](https://docs.victoriametrics.com/keyconcepts#raw-samples) in streaming mode by time and by labels before data is written to remote storage
 (or local storage for single-node VictoriaMetrics).
 The aggregation is applied to all the metrics received via any [supported data ingestion protocol](https://docs.victoriametrics.com#how-to-import-time-series-data)
 and/or scraped from [Prometheus-compatible targets](https://docs.victoriametrics.com#how-to-scrape-prometheus-exporters-such-as-node-exporter)
 after applying all the configured [relabeling stages](https://docs.victoriametrics.com/vmagent#relabeling).
 _By default, stream aggregation ignores timestamps associated with the input [samples](https://docs.victoriametrics.com/keyconcepts#raw-samples).
 It expects that the ingested samples have timestamps close to the current time. See [how to ignore old samples](./configuration/#ignoring-old-samples)._
 ## Next steps
 {{% section %}}
--- a/docs/stream-aggregation/_index.md
+++ b/docs/stream-aggregation/_index.md
@ -0,0 +1,13 @@
 ---
 weight: 10
 title: Streaming aggregation
 menu:
  docs:
    identifier: stream-aggregation
    parent: 'victoriametrics'
    weight: 10
 aliases:
 - /stream-aggregation/
 - /stream-aggregation/index.html
 ---
 {{% content "README.md" %}}
--- a/docs/stream-aggregation/common-mistakes.md
+++ b/docs/stream-aggregation/common-mistakes.md
@ -0,0 +1,115 @@
 ---
 sort: 5
 weight: 5
 title: Common mistakes
 menu:
  docs:
    identifier: stream-aggregation-common-mistakes
    parent: 'stream-aggregation'
    weight: 5
 aliases:
 - /stream-aggregation/common-mistakes/
 - /stream-aggregation/common-mistakes/index.html
 ---
 ## Place aggregation agents behind a load balancer
 Partial aggregation (only a subset of all data, which satisfies [`match`](./configuration/#match) expression was pushed to an aggregation agent) is not acceptable.
 It produces wrong aggregations which are not usable and not comparable to equivalent [recording rules](https://docs.victoriametrics.com/vmalert#recording-rules).
 To keep aggregation results consistent, it should be either fully processed on a single VMAgent or data can be sharded across multiple VMAgents by metric name.
 ## Create separate aggregator for each recording rule
 As was mentioned in [use case scenarios](./use-cases.md#recording-rules-alternative), stream aggregation can be considered as a substitution for [recording rules](https://docs.victoriametrics.com/vmalert#recording-rules), but straightforward conversion of recording rules to [stream aggregation config](./configuration/#configuration-file-reference) can lead to inefficient resource usage on the component it's configured on ([VMAgent](https://docs.victoriametrics.com/vmagent) or [VMSingle](https://docs.victoriametrics.com/vmsingle)).
 To optimize this, we recommend merging together aggregations which only differ in match expressions. E.g:
 Given list of recording rules:
 ```yaml
 - expr: sum(rate(node_cpu_seconds_total{mode!="idle",mode!="iowait",mode!="steal"}[3m])) BY (instance)
  record: instance:node_cpu:rate:sum
 - expr: sum(rate(node_network_receive_bytes_total[3m])) BY (instance)
  record: instance:node_network_receive_bytes:rate:sum
 - expr: sum(rate(node_network_transmit_bytes_total[3m])) BY (instance)
  record: instance:node_network_transmit_bytes:rate:sum
 - expr: sum(rate(node_cpu_seconds_total{mode!="idle",mode!="iowait",mode!="steal"}[5m]))
  record: cluster:node_cpu:sum_rate5m
 ```
 can be converted to aggregation rules:
 ```yaml
 - match: node_cpu_seconds_total{mode!="idle",mode!="iowait",mode!="steal"}
  interval: 3m
  by:
  - instance
  output_relabel_configs:
  - source_labels: [__name__]
    target_label: __name__
    replacement: instance:node_cpu:rate:sum
 - match: node_network_receive_bytes_total
  interval: 3m
  by:
  - instance
  output_relabel_configs:
  - source_labels: [__name__]
    target_label: __name__
    replacement: instance:node_network_receive_bytes:rate:sum
 - match: node_network_transmit_bytes_total
  interval: 3m
  by:
  - instance
  output_relabel_configs:
  - source_labels: [__name__]
    target_label: __name__
    replacement: instance:node_network_transmit_bytes:rate:sum
 - match: node_cpu_seconds_total{mode!="idle",mode!="iowait",mode!="steal"}
  interval: 5m
  output_relabel_configs:
  - source_labels: [__name__]
    target_label: __name__
    replacement: cluster:node_cpu:sum_rate5m
 ```
 note, that first 3 aggregation rules differ only in [`match`](./configuration/#match), so they can be merged together:
 ```yaml
 - match:
  - node_cpu_seconds_total{mode!="idle",mode!="iowait",mode!="steal"}
  - node_network_receive_bytes_total
  - node_network_transmit_bytes_total
  interval: 3m
  by:
  - instance
  output_relabel_configs:
  - source_labels: [__name__]
    target_label: __name__
    regex: regex: "(.+)(_seconds)?(_total)?:.+"
    replacement: cluster:node_cpu:sum_rate5m
 - match: node_cpu_seconds_total{mode!="idle",mode!="iowait",mode!="steal"}
  interval: 5m
  output_relabel_configs:
  - source_labels: [__name__]
    target_label: __name__
    replacement: cluster:node_cpu:sum_rate5m
 ```
 **Note**: having separate aggregator for a certain [`match`](./configuration/#match) expression can only be justified when aggregator cannot keep up with all
 the data pushed to an aggregator within an aggregation interval
 ## Use identical --remoteWrite.streamAggr.config for all remote writes
 As it's described in [previous](#create-separate-aggregator-for-each-recording-rule) case having many aggregators leads to increased resource usage so having `n`
 identical aggregation configurations `-remoteWrite.streamAggr.config` for multiple `-remoteWrite.url` requires `n * x` resources.
 As an optimization, we suggest using `-streamAggr.config` as a replacement for `-remoteWrite.streamAggr.config`.
 It places the global aggregator in front of all remote writes, which helps to reduce resource usage.
 ## Treat aggregated metrics in the same manner as original ones
 Stream aggregation allows to keep for aggregation result the name of a source metric using [`keep_metric_names:`](./configuration/#keep-metric-names) `true`.
 But graphs and alerts, which were previously used for a raw metric can become incorrect for aggregated one.
 Dashboards and alerts should be updated according to aggregation configurations.
--- a/docs/stream-aggregation/configuration/README.md
+++ b/docs/stream-aggregation/configuration/README.md
@ -0,0 +1,116 @@
 Stream aggregation can be configured via the following command-line flags:
 - `-streamAggr.config` at [single-node VictoriaMetrics](https://docs.victoriametrics.com/)
  and at [vmagent](https://docs.victoriametrics.com/vmagent).
 - `-remoteWrite.streamAggr.config` at [vmagent](https://docs.victoriametrics.com/vmagent) only.
  This flag can be specified individually per each `-remoteWrite.url` and aggregation will happen independently for each of them.
  This allows writing different aggregates to different remote storage destinations.
 These flags must point to a file containing [stream aggregation config](#configuration-file-reference).
 The file may contain `%{ENV_VAR}` placeholders which are substituted by the corresponding `ENV_VAR` environment variable values.
 By default, the following data is written to the storage when stream aggregation is enabled:
 - the aggregated samples;
 - the raw input samples, which didn't match any [`match`](#match) option in the provided [config](#configuration-file-reference)
 This behaviour can be changed via the following command-line flags:
 - `-streamAggr.keepInput` at [single-node VictoriaMetrics](https://docs.victoriametrics.com)
  and [vmagent](https://docs.victoriametrics.com/vmagent). At [vmagent](https://docs.victoriametrics.com/vmagent)
  `-remoteWrite.streamAggr.keepInput` flag can be specified individually per each `-remoteWrite.url`.
  If one of these flags is set, then all the input samples are written to the storage alongside the aggregated samples.
 - `-streamAggr.dropInput` at [single-node VictoriaMetrics](https://docs.victoriametrics.com)
  and [vmagent](https://docs.victoriametrics.com/vmagent). At [vmagent](https://docs.victoriametrics.com/vmagent)
  `-remoteWrite.streamAggr.dropInput` flag can be specified individually per each `-remoteWrite.url`.
  If one of these flags are set, then all the input samples are dropped, while only the aggregated samples are written to the storage.
 ## Configuration File Reference
 ### Overview
 Stream aggregation config file contains YAML formatted configs and may be referred via
 `-streamAggr.config` command-line flag at [single-node VictoriaMetrics](https://docs.victoriametrics.com)
 and [vmagent](https://docs.victoriametrics.com/vmagent). At [vmagent](https://docs.victoriametrics.com/vmagent) `-remoteWrite.streamAggr.config`
 command-line flag can be specified individually per each `-remoteWrite.url` or just once, which
 enables same aggregation rules for each `-remoteWrite.url`.
 ### Example configuration
 ```yaml
 - match: 'http_request_duration_seconds_bucket{env=~"prod|staging"}'
  interval: 1m
  by: [vmrange]
  outputs: [total]
 ```
 * [`name`](?selfref=true#name) `(string: "none")` - name of the given streaming aggregation config. 
  If it is set, then it is used as `name` label in the exposed metrics for the given aggregation config at /metrics page.
  See monitoring related information [here](https://docs.victoriametrics.com/vmagent#monitoring) and [here](https://docs.victoriametrics.com/#monitoring)
 * [`match`](?selfref=true#match) `(list<string> or string: [])` - an optional filter for incoming samples to aggregate.
  It can contain arbitrary Prometheus series selector
  according to [filtering concepts](https://docs.victoriametrics.com/keyconcepts#filtering).
  If match isn't set, then all the incoming samples are aggregated.
  match also can contain a list of series selectors. Then the incoming samples are aggregated
  if they match at least a single series selector.
 * [`interval`](?selfref=true#interval)  `(string: "", required)` - interval for the aggregation. The aggregated stats are sent to 
  remote storage once per interval.
 * [`dedup_interval`](?selfref=true#dedup_interval) `(string:"")` - interval for de-duplication of input samples before the aggregation.
  Samples are de-duplicated on a per-series basis. See [timeseries](https://docs.victoriametrics.com/keyconcepts#time-series) and [deduplication](#deduplication)
  The deduplication is performed after [`input_relabel_configs`](#input-relabel-configs) relabeling is applied. By default, the deduplication is disabled
  unless `-remoteWrite.streamAggr.dedupInterval` or `-streamAggr.dedupInterval` command-line flags are set.
 * [`staleness_interval`](?selfref=true#staleness_interval) `(string:2*interval)` - interval for resetting the per-series state if no new samples
  are received during this interval for the following outputs:
  * [`rate_avg`](./outputs/#rate_avg)
  * [`rate_sum`](./outputs/#rate_sum)
  * [`total`](./outputs/#total)
  * [`total_prometheus`](./outputs/#total_prometheus)
  * [`increase`](./outputs/#increase)
  * [`increase_prometheus`](./outputs/#increase_prometheus)
  * [`histogram_bucket`](./outputs/#histogram_bucket)
  Check [staleness](#staleness) for more details.
 * [`no_align_flush_to_interval`](?selfref=true#no_align_flush_to_interval) `(bool: false)` - disables aligning of flush times for the aggregated data to multiples of interval.
  By default, flush times for the aggregated data is aligned to multiples of interval.
  For example:
  * if [`interval:`](#interval) `1m` is set, then flushes happen at the end of every minute,
  * if [`interval:`](#interval) `1h` is set, then flushes happen at the end of every hour
 * [`flush_on_shutdown`](?selfref=true#flush_on_shutdown) `(bool: false)` - instructs to flush aggregated data to the storage on the first and the last intervals
  during vmagent starts, restarts or configuration reloads.
  Incomplete aggregated data isn't flushed to the storage by default, since it is usually confusing.
 * [`without`](?selfref=true#without) `(list<string>: [])` - list of labels, which must be removed from the output aggregation.
  See [aggregation by labels](#aggregating-by-labels)
 * [`by`](?selfref=true#by) `(list<string>: [])` - list of labels, which must be preserved in the output aggregation.
  See [aggregation by labels](#aggregating-by-labels)
 * [`outputs`](?selfref=true#outputs) `(list<string>:[], required)` - list of aggregations to perform on the input data.
  See [aggregation outputs](#outputs).
 * [`keep_metric_names`](?selfref=true#keep_input_names) `(bool: false)` - instructs keeping the original metric names for the aggregated samples.
  This option can be set only if outputs list contains only a single output.
  By default, a special suffix is added to original metric names in the aggregated samples.
  See [output metric names](../#output-metric-names)
 * [`ignore_old_samples`](?selfref=true#ignore_old_samples) `(bool: false)` - instructs ignoring input samples with old timestamps outside the current aggregation interval.
  See [ignoring old samples](../#ignoring-old-samples)
  See also [-remoteWrite.streamAggr.ignoreOldSamples](#remote-write-ignore-old-samples-flag) or [-streamAggr.ignoreOldSamples](#ignore-old-samples-flag) command-line flag.
 * [`ignore_first_intervals`](?selfref=true#ignore_first_intervals) `(int: 0)` - instructs ignoring the first N aggregation intervals after process start.
  See [ignore first intervals on start](../#ignore-aggregation-intervals-on-start)
  See also [-remoteWrite.streamAggr.ignoreFirstIntervals](#remote-write-ignore-first-intervals-flag) or [-streamAggr.ignoreFirstIntervals](#ignore-first-intervals-flag) command-line flags.
 * [`drop_input_labels`](?selfref=true#drop_input_labels) `(bool: false)` - instructs dropping the given labels from input samples.
  The labels' dropping is performed before [`input_relabel_configs`](#input-relabel-configs) are applied.
  This also means that the labels are dropped before [deduplication](../#deduplication) and stream aggregation.
 * [`input_relabel_configs`](?selfref=true#output_relabel_configs) `(array<relabel_config>: [])` - relabeling rules, which are applied to the incoming samples
  after they pass the match filter and before being aggregated. See [relabeling](../#relabeling)
 * [`output_relabel_configs`](?selfref=true#output_relabel_configs) `(array<relabel_config>: [])` - relabeling rules, which are applied to the aggregated output metrics.
 The file can contain multiple aggregation configs. The aggregation is performed independently
 per each specified config entry.
 ### Configuration update
 [vmagent](https://docs.victoriametrics.com/vmagent) and [single-node VictoriaMetrics](https://docs.victoriametrics.com/vmagent)
 support the following approaches for hot reloading stream aggregation configs from `-remoteWrite.streamAggr.config` and `-streamAggr.config`:
 * By sending `SIGHUP` signal to `vmagent` or `victoria-metrics` process:
  ```sh
  kill -SIGHUP `pidof vmagent`
  ```
 * By sending HTTP request to `/-/reload` endpoint (e.g. `http://vmagent:8429/-/reload` or `http://victoria-metrics:8428/-/reload).
--- a/docs/stream-aggregation/configuration/_index.md
+++ b/docs/stream-aggregation/configuration/_index.md
@ -0,0 +1,14 @@
 ---
 sort: 4
 weight: 4
 title: Configuration
 menu:
  docs:
    identifier: stream-aggregation-config
    parent: stream-aggregation
    weight: 4
 aliases:
 - /stream-aggregation/configuration/
 - /stream-aggregation/configuration/index.html
 ---
 {{% content "README.md" %}}
--- a/docs/stream-aggregation/configuration/outputs/README.md
+++ b/docs/stream-aggregation/configuration/outputs/README.md
@ -0,0 +1,553 @@
 The aggregations are calculated during the [`interval`](../#interval) and then sent to the storage once
 per [`interval`](../#interval). The aggregated samples are named according to [`output metric naming`](../#output-metric-names).
 If [`by`](../#by) and [`without`](../#without) lists are set then the [`aggregation by labels`](../#aggregating-by-labels) is performed additionally to aggregation by `interval`.
 Below are aggregation functions that can be set in the [`outputs`](../#outputs):
 ## avg
 `avg` returns the average over input [sample values](https://docs.victoriametrics.com/keyconcepts#raw-samples).
 `avg` makes sense only for aggregating [gauges](https://docs.victoriametrics.com/keyconcepts#gauge).
 For example, see below time series produced by config with [`aggregation interval:`](../#interval) `1m` and [`by:`](../#by) `[instance]` and  the regular query:
 ![avg aggregation](./avg.webp)
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 1m
 outputs:
 - avg
 ```
 ### MetricsQL
 ```metricsql
 sum(sum_over_time(some_metric[interval])) / sum(count_over_time(some_metric[5m]))
 ```
 ### See also
 - [`min`](#min)
 - [`max`](#max)
 - [`sum_samples`](#sum_samples)
 - [`count_samples`](#count_samples)
 ## count_samples
 `count_samples` counts the number of input [samples](https://docs.victoriametrics.com/keyconcepts#raw-samples) over the given [`interval`](../#interval).
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 1m
 outputs:
 - count_samples
 ```
 ### MetricsQL
 ```metricsql
 sum(count_over_time(some_metric[interval]))
 ```
 ### See also
 - [`count_series`](#count_series)
 - [`sum_samples`](#sum_samples)
 ## count_series
 `count_series` counts the number of unique [time series](https://docs.victoriametrics.com/keyconcepts#time-series) over the given [`interval`](../#interval).
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 1m
 outputs:
 - count_series
 ```
 ### MetricsQL
 ```metricsql
 count(last_over_time(some_metric[interval]))
 ```
 ### See also
 - [`count_samples`](#count_samples)
 - [`unique_samples`](#unique_samples)
 ## histogram_bucket
 `histogram_bucket` returns [VictoriaMetrics histogram buckets](https://valyala.medium.com/improving-histogram-usability-for-prometheus-and-grafana-bc7e5df0e350)
  for the input [sample values](https://docs.victoriametrics.com/keyconcepts#raw-samples) over the given [`interval`](../#interval).
 `histogram_bucket` makes sense only for aggregating [gauges](https://docs.victoriametrics.com/keyconcepts#gauge).
 See how to aggregate regular histograms [here](#aggregating-histograms).
 The results of `histogram_bucket` is equal to the following [MetricsQL](../../MetricsQL.md) query:
 Aggregating irregular and sporadic metrics (received from [Lambdas](https://aws.amazon.com/lambda/)
 or [Cloud Functions](https://cloud.google.com/functions)) can be controlled via [staleness_interval](#staleness) option.
 ### Example
 ```yaml
 match:
 - some_histogram_bucket
 interval: 1m
 outputs:
 - histogram_bucket
 ```
 ### MetricsQL
 ```metricsql
 sum(histogram_over_time(some_histogram_bucket[1m])) by (vmrange)
 ```
 ### See also
 - [quantiles](#quantiles)
 - [min](#min)
 - [max](#max)
 - [avg](#avg)
 ## increase
 `increase` returns the increase of input [time series](https://docs.victoriametrics.com/keyconcepts#time-series) over the given [`interval`](../#interval).
 `increase` makes sense only for aggregating [counters](https://docs.victoriametrics.com/keyconcepts#counter).
 `increase` assumes that all the counters start from 0. For example, if the first seen sample for new [time series](https://docs.victoriametrics.com/keyconcepts#time-series)
 is `10`, then `increase` assumes that the time series has been increased by `10`. If you need ignoring the first sample for new time series,
 then take a look at [increase_prometheus](#increase_prometheus).
 For example, see below time series produced by config with [`aggregation interval`](../#interval) `1m` and `by: ["instance"]` and the regular query:
 ![increase aggregation](./increase.webp)
 Aggregating irregular and sporadic metrics (received from [Lambdas](https://aws.amazon.com/lambda/)
 or [Cloud Functions](https://cloud.google.com/functions)) can be controlled via [staleness_interval](../#staleness") option.
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 2m
 outputs:
 - increase
 ```
 ### MetricsQL
 ```metricsql
 sum(increase_pure(some_counter[2m]))
 ```
 ### See also
 - [`increase_prometheus`](#increase_prometheus)
 - [`total`](#total)
 ## increase_prometheus
 `increase_prometheus` returns the increase of input [time series](https://docs.victoriametrics.com/keyconcepts#time-series) over the given [`interval`](../#interval).
 `increase_prometheus` makes sense only for aggregating [counters](https://docs.victoriametrics.com/keyconcepts#counter).
 `increase_prometheus` skips the first seen sample value per each [time series](https://docs.victoriametrics.com/keyconcepts#time-series).
 If you need taking into account the first sample per time series, then take a look at [increase](../#increase).
 Aggregating irregular and sporadic metrics (received from [Lambdas](https://aws.amazon.com/lambda/)
 or [Cloud Functions](https://cloud.google.com/functions)) can be controlled via [staleness_interval](../#staleness) option.
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 5m
 outputs:
 - increase_prometheus
 ```
 ### MetricsQL
 ```metricsql
 sum(increase_prometheus(some_counter[5m]))
 ```
 ### See also
 - [increase](#increase)
 - [total](#total)
 - [total_prometheus](#total_prometheus)
 ## last
 `last` returns the last input [sample value](https://docs.victoriametrics.com/keyconcepts#raw-samples) over the given [`interval`](../#interval).
 ### Example
 ```yaml
 match:
 - some_metric
 interval: 5m
 outputs:
 - last
 ```
 ### MetricsQL
 ```metricsql
 last_over_time(some_metric[interval])
 ```
 ### See also
 - [`min`](#min)
 - [`max`](#max)
 - [`avg`](#avg).
 ## max
 `max` returns the maximum input [sample value](https://docs.victoriametrics.com/keyconcepts#raw-samples) over the given [`interval`](../#interval).
 For example, see below time series produced by config with [`aggregation interval:`](../#interval) `1m` and the regular query:
 ![total aggregation](./max.webp)
 ### Example
 ```yaml
 match:
 - some_metric
 interval: 5m
 outputs:
 - max
 ```
 ### MetricsQL
 ```metricsql
 max(max_over_time(some_metric[interval]))
 ```
 ### See also
 - [`min`](#min)
 - [`avg`](#avg)
 ## min
 `min` returns the minimum input [sample value](https://docs.victoriametrics.com/keyconcepts#raw-samples) over the given `interval`.
 For example, see below time series produced by config with [`aggregation interval:`](../#interval) `1m` and the regular query:
 ![min aggregation](./min.webp)
 ### Example
 ```yaml
 match:
 - some_metric
 interval: 5m
 outputs:
 - min
 ```
 ### MetricsQL
 ```metricsql
 min(min_over_time(some_metric[5m]))
 ```
 ### See also
 - [`max`](#max)
 - [`avg`](#avg)
 ## quantiles
 `quantiles(phi1, ..., phiN)` returns [percentiles](https://en.wikipedia.org/wiki/Percentile) for the given `phi*`
 over the input [sample values](https://docs.victoriametrics.com/keyconcepts#raw-samples) on the given `interval`.
 `phi` must be in the range `[0..1]`, where `0` means `0th` percentile, while `1` means `100th` percentile.
 `quantiles(...)` makes sense only for aggregating [gauges](https://docs.victoriametrics.com/keyconcepts#gauge).
 ### Example
 ```yaml
 match:
 - temperature
 interval: 24h
 outputs:
 - quantiles(0.55, 0.99)
 ```
 ### MetricsQL
 ```metricsql
 histogram_quantiles("quantile", 0.55, 0.99, sum(histogram_over_time(temperature[24h])) by (vmrange))
 ```
 ### See also
 - [`histogram_bucket`](#histogram_bucket)
 - [`min`](#min)
 - [`avg`](#avg)
 ## rate_avg
 `rate_avg` returns the average of average per-second of input [time series](https://docs.victoriametrics.com/keyconcepts#time-series) over the given [`interval`](../#interval).
 `rate_avg` makes sense only for aggregating [counters](https://docs.victoriametrics.com/keyconcepts#counter).
 See also [rate_sum](#rate_sum) and [total](#total) outputs.
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 5m
 outputs:
 - rate_avg
 ```
 ### MetricsQL
 ```metricsql
 avg(rate(some_counter[5m]))
 ```
 ## rate_sum
 `rate_sum` returns the sum of average per-second change of input [time series](https://docs.victoriametrics.com/keyconcepts#time-series) over the given [`interval`](../#interval).
 `rate_sum` makes sense only for aggregating [counters](https://docs.victoriametrics.com/keyconcepts#counter).
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 2m
 outputs:
 - rate_sum
 ```
 ### MetricsQL
 ```metricsql
 sum(rate(some_counter[2m]))
 ```
 ### See also
 - [`rate_avg`](#rate_avg)
 - [`total`](#total)
 ## stddev
 `stddev` returns [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) for the input [sample values](https://docs.victoriametrics.com/keyconcepts#raw-samples)
 over the given [`interval`](../#interval).
 `stddev` makes sense only for aggregating [gauges](https://docs.victoriametrics.com/keyconcepts#gauge).
 ### Example
 ```yaml
 match:
 - some_metric
 interval: 2m
 outputs:
 - stddev
 ```
 ### MetricsQL
 ```metricsql
 histogram_stddev(sum(histogram_over_time(some_metric[2m])) by (vmrange))
 ```
 ### See also
 - [`stdvar`](#stdvar)
 - [`avg`](#avg).
 ## stdvar
 `stdvar` returns [standard variance](https://en.wikipedia.org/wiki/Variance) for the input [sample values](https://docs.victoriametrics.com/keyconcepts#raw-samples)
 over `he given [`interval`](../#interval).
 `stdvar` makes sense only for aggregating [gauges](https://docs.victoriametrics.com/keyconcepts#gauge).
 For example, see below time series produced by config with [`aggregation interval`](../#interval) `1m` and the regular query:
 ![stdvar aggregation](./stdvar.webp)
 ### Example
 ```yaml
 match:
 - some_metric
 interval: 10m
 outputs:
 - stdvar
 ```
 ### MetricsQL
 ```metricsql 
 histogram_stdvar(sum(histogram_over_time(some_metric[10m])) by (vmrange))
 ```
 ### See also
 - [`stddev`](#stddev)
 - [`avg`](#avg)
 ## sum_samples
 `sum_samples` sums input [sample values](https://docs.victoriametrics.com/keyconcepts#raw-samples) over the given [`interval`](../#interval).
 `sum_samples` makes sense only for aggregating [gauges](https://docs.victoriametrics.com/keyconcepts#gauge).
 For example, see below time series produced by config with [`aggregation interval`](../#interval) `1m` and the regular query:
 ![sum_samples aggregation](./sum-samples.webp)
 ### Example
 ```yaml
 match:
 - some_metric
 interval: 5m
 outputs:
 - sum_samples
 ```
 ### MetricsQL
 ```metricsql 
 sum(sum_over_time(some_metric[5m]))
 ```
 ### See also
 - [`count_samples`](#count_samples)
 - [`count_series`](#count_series)
 ## total
 `total` generates output [counter](https://docs.victoriametrics.com/keyconcepts#counter) by summing the input counters over the given [`interval`](../#interval).
 `total` makes sense only for aggregating [counters](https://docs.victoriametrics.com/keyconcepts#counter).
 `total` assumes that all the counters start from 0. For example, if the first seen sample for new [time series](https://docs.victoriametrics.com/keyconcepts#time-series)
 is `10`, then `total` assumes that the time series has been increased by `10`. If you need ignoring the first sample for new time series,
 then take a look at [total_prometheus](#total_prometheus).
 For example, see below time series produced by config with [`aggregation interval:`](../#interval) `1m` and [`by:`](../#by) `[instance]` and the regular query:
 ![total aggregation](./total.webp)
 `total` is not affected by [counter resets](https://docs.victoriametrics.com/keyconcepts#counter) -
 it continues to increase monotonically with respect to the previous value.
 The counters are most often reset when the application is restarted.
 For example:
 ![total aggregation counter reset](./total-reset.webp)
 The same behavior occurs when creating or deleting new series in an aggregation group -
 `total` output increases monotonically considering the values of the series set.
 An example of changing a set of series can be restarting a pod in the Kubernetes.
 This changes pod name label, but the `total` accounts for such a scenario and doesn't reset the state of aggregated metric.
 Aggregating irregular and sporadic metrics (received from [Lambdas](https://aws.amazon.com/lambda/)
 or [Cloud Functions](https://cloud.google.com/functions)) can be controlled via [staleness_interval](../#staleness) option.
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 1m
 outputs:
 - total
 ```
 ### MetricsQL
 ```metricsql
 sum(running_sum(increase_pure(some_counter[1m])))
 ```
 ### See also
 - [`total_prometheus`](#total_prometheus)
 - [`increase`](#increase)
 - [`increase_prometheus`](#increase_prometheus)
 ## total_prometheus
 `total_prometheus` generates output [counter](https://docs.victoriametrics.com/keyconcepts#counter) by summing the input counters over the given [`interval`](../#interval).
 `total_prometheus` makes sense only for aggregating [counters](https://docs.victoriametrics.com/keyconcepts#counter).
 `total_prometheus` skips the first seen sample value per each [time series](https://docs.victoriametrics.com/keyconcepts#time-series).
 If you need taking into account the first sample per time series, then take a look at [total](#total).
 `total_prometheus` is not affected by [counter resets](https://docs.victoriametrics.com/keyconcepts#counter) -
 it continues to increase monotonically with respect to the previous value.
 The counters are most often reset when the application is restarted.
 Aggregating irregular and sporadic metrics (received from [Lambdas](https://aws.amazon.com/lambda/)
 or [Cloud Functions](https://cloud.google.com/functions)) can be controlled via [staleness_interval](#staleness) option.
 ### Example
 ```yaml
 match:
 - some_counter
 interval: 1m
 outputs:
 - total_prometheus
 ```
 ### MetricsQL
 ```metricsql
 sum(running_sum(increase_prometheus(some_counter[1m])))
 ```
 ### See also
 - [`total`](#total)
 - [`increase`](#increase)
 - [`increase_prometheus`](#increase_prometheus)
 ## unique_samples
 `unique_samples` counts the number of unique sample values over the given [`interval`](../#interval).
 `unique_samples` makes sense only for aggregating [gauges](https://docs.victoriametrics.com/keyconcepts#gauge).
 ### Example
 ```yaml
 match:
 - some_metric
 interval: 2m
 outputs:
 - unique_samples
 ```
 ### MetricsQL
 ```metricsql
 count(count_values_over_time(some_metric[2m]))
 ```
 ### See also
 - [`sum_samples`](#sum_samples)
 - [`count_series`](#count_series)
--- a/docs/stream-aggregation/configuration/outputs/_index.md
+++ b/docs/stream-aggregation/configuration/outputs/_index.md
@ -0,0 +1,14 @@
 ---
 sort: 1
 weight: 1
 title: Outputs
 menu:
  docs:
    identifier: stream-aggregation-config-outputs
    parent: stream-aggregation-config
    weight: 1
 aliases:
 - /stream-aggregation/outputs/
 - /stream-aggregation/outputs/index.html
 ---
 {{% content "README.md" %}}
--- a/docs/stream-aggregation/configuration/outputs/avg.webp
+++ b/docs/stream-aggregation/configuration/outputs/avg.webp
--- a/docs/stream-aggregation/configuration/outputs/increase.webp
+++ b/docs/stream-aggregation/configuration/outputs/increase.webp
--- a/docs/stream-aggregation/configuration/outputs/max.webp
+++ b/docs/stream-aggregation/configuration/outputs/max.webp
--- a/docs/stream-aggregation/configuration/outputs/min.webp
+++ b/docs/stream-aggregation/configuration/outputs/min.webp
--- a/docs/stream-aggregation/configuration/outputs/stdvar.webp
+++ b/docs/stream-aggregation/configuration/outputs/stdvar.webp
--- a/docs/stream-aggregation/configuration/outputs/sum-samples.webp
+++ b/docs/stream-aggregation/configuration/outputs/sum-samples.webp
--- a/docs/stream-aggregation/configuration/outputs/total-reset.webp
+++ b/docs/stream-aggregation/configuration/outputs/total-reset.webp
--- a/docs/stream-aggregation/configuration/outputs/total.webp
+++ b/docs/stream-aggregation/configuration/outputs/total.webp
--- a/docs/stream-aggregation/key-concepts.md
+++ b/docs/stream-aggregation/key-concepts.md
@ -0,0 +1,243 @@
 ---
 sort: 2
 weight: 2
 title: Key concepts
 menu:
  docs:
    identifier: stream-aggregation-key-concepts
    parent: 'stream-aggregation'
    weight: 2
 aliases:
 - /stream-aggregation/key-concepts/index.html
 - /stream-aggretation/key-concepts/
 ---
 [Single-node VictoriaMetrics](https://docs.victoriametrics.com/) supports relabeling,
 deduplication and stream aggregation for all the received data, scraped or pushed. 
 The processed data is then stored in local storage and **can't be forwarded further**.
 [vmagent](https://docs.victoriametrics.com/vmagent) supports relabeling, deduplication and stream aggregation for all 
 the received data, scraped or pushed. Then, the collected data will be forwarded to specified `-remoteWrite.url` destinations.
 The data processing order is the following:
 1. All the received data is [relabeled](https://docs.victoriametrics.com/vmagent#relabeling) according to 
   specified `-remoteWrite.relabelConfig`;
 2. All the received data is [deduplicated](#deduplication)
   according to specified `-streamAggr.dedupInterval`;
 3. All the received data is aggregated according to specified `-streamAggr.config`;
 4. The resulting data from p1 and p2 is then replicated to each `-remoteWrite.url`;
 5. Data sent to each `-remoteWrite.url` can be additionally relabeled according to the 
   corresponding `-remoteWrite.urlRelabelConfig` (set individually per URL);
 6. Data sent to each `-remoteWrite.url` can be additionally deduplicated according to the
   corresponding `-remoteWrite.streamAggr.dedupInterval` (set individually per URL);
 7. Data sent to each `-remoteWrite.url` can be additionally aggregated according to the
   corresponding `-remoteWrite.streamAggr.config` (set individually per URL). Please note, it is not recommended
   to use `-streamAggr.config` and `-remoteWrite.streamAggr.config` together, unless you understand the complications.
 Typical scenarios for data routing with vmagent:
 1. **Aggregate incoming data and replicate to N destinations**. For this one should configure `-streamAggr.config`
 to aggregate the incoming data before replicating it to all the configured `-remoteWrite.url` destinations.
 2. **Individually aggregate incoming data for each destination**. For this on should configure `-remoteWrite.streamAggr.config`
 for each `-remoteWrite.url` destination. [Relabeling](https://docs.victoriametrics.com/vmagent#relabeling) 
 via `-remoteWrite.urlRelabelConfig` can be used for routing only selected metrics to each `-remoteWrite.url` destination.
 ## Deduplication
 [vmagent](https://docs.victoriametrics.com/vmagent) supports online [de-duplication](https://docs.victoriametrics.com#deduplication) of samples
 before sending them to the configured `-remoteWrite.url`. The de-duplication can be enabled via the following options:
 - By specifying the desired de-duplication interval via `-streamAggr.dedupInterval` command-line flag for all received data 
  or via `-remoteWrite.streamAggr.dedupInterval` command-line flag for the particular `-remoteWrite.url` destination.
  For example, `./vmagent -remoteWrite.url=http://remote-storage/api/v1/write -remoteWrite.streamAggr.dedupInterval=30s` instructs `vmagent` to leave
  only the last sample per each seen [time series](https://docs.victoriametrics.com/keyconcepts#time-series) per every 30 seconds.
  The de-deduplication is performed after applying [relabeling](https://docs.victoriametrics.com/vmagent#relabeling) and
  before performing the aggregation.
  If the `-remoteWrite.streamAggr.config` and / or `-streamAggr.config` is set, then the de-duplication is performed individually per each
  [stream aggregation config](./configuration/#configuration-file-reference) for the matching samples after applying [input_relabel_configs](#relabeling).
 - By specifying `dedup_interval` option individually per each [stream aggregation config](./configuration/#configuration-file-reference) 
  in `-remoteWrite.streamAggr.config` or `-streamAggr.config` configs.
 [Single-node VictoriaMetrics](https://docs.victoriametrics.com/) supports two types of de-duplication:
 - After storing the duplicate samples to local storage. See [`-dedup.minScrapeInterval`](https://docs.victoriametrics.com/#deduplication) command-line option.
 - Before storing the duplicate samples to local storage. This type of de-duplication can be enabled via the following options:
  - By specifying the desired de-duplication interval via `-streamAggr.dedupInterval` command-line flag.
    For example, `./victoria-metrics -streamAggr.dedupInterval=30s` instructs VictoriaMetrics to leave only the last sample per each
    seen [time series](https://docs.victoriametrics.com/keyconcepts#time-series) per every 30 seconds.
    The de-duplication is performed after applying [relabeling](https://docs.victoriametrics.com/#relabeling) and before performing the aggregation.
    If the `-remtoeWrite.streamAggr.config` and / or `-streamAggr.config` is set, then the de-duplication is performed individually per each
    [stream aggregation config](./configuration/#configuration-file-reference) for the matching samples after applying [input_relabel_configs](#relabeling).
  - By specifying `dedup_interval` option individually per each [stream aggregation config](./configuration/#configuration-file-reference)
    in `-remoteWrite.streamAggr.config` or `-streamAggr.config` configs.
 It is possible to drop the given labels before applying the de-duplication. See [these docs](#dropping-unneeded-labels).
 The online de-duplication uses the same logic as [`-dedup.minScrapeInterval` command-line flag](https://docs.victoriametrics.com#deduplication) at VictoriaMetrics.
 ## Ignoring old samples
 By default, all the input samples are taken into account during stream aggregation. If samples with old timestamps 
 outside the current [aggregation interval](./configuration/#interval) must be ignored, then the following options can be used:
 - To pass `-streamAggr.ignoreOldSamples` command-line flag to [single-node VictoriaMetrics](https://docs.victoriametrics.com)
  or to [vmagent](https://docs.victoriametrics.com/vmagent). At [vmagent](https://docs.victoriametrics.com/vmagent)
  `-remoteWrite.streamAggr.ignoreOldSamples` flag can be specified individually per each `-remoteWrite.url`.
  This enables ignoring old samples for all the [aggregation configs](./configuration/#configuration-file-reference).
 - To set [`ignore_old_samples:`](./configuration/#ignore-old-samples) `true` option at the particular [aggregation config](./configuration/#configuration-file-reference).
  This enables ignoring old samples for that particular aggregation config.
 ## Ignore aggregation intervals on start
 Streaming aggregation results may be incorrect for some time after the restart of [vmagent](https://docs.victoriametrics.com/vmagent)
 or [single-node VictoriaMetrics](https://docs.victoriametrics.com) until all the buffered [samples](https://docs.victoriametrics.com/keyconcepts#raw-samples)
 are sent from remote sources to the `vmagent` or single-node VictoriaMetrics via [supported data ingestion protocols](https://docs.victoriametrics.com/vmagent#how-to-push-data-to-vmagent).
 In this case it may be a good idea to drop the aggregated data during the first `N` [aggregation intervals](./configuration/#interval)
 just after the restart of `vmagent` or single-node VictoriaMetrics. This can be done via the following options:
 - Set `-streamAggr.ignoreFirstIntervals=<intervalsCount>` command-line flag to [single-node VictoriaMetrics](https://docs.victoriametrics.com)
  or to [vmagent](https://docs.victoriametrics.com/vmagent) to skip first `<intervalsCount>` [aggregation intervals](./configuration/#interval)
  from persisting to the storage. At [vmagent](https://docs.victoriametrics.com/vmagent)
  `-remoteWrite.streamAggr.ignoreFirstIntervals=<intervalsCount>` flag can be specified individually per each `-remoteWrite.url`.
  It is expected that all incomplete or queued data will be processed during specified `<intervalsCount>` 
  and all subsequent aggregation intervals will produce correct data.
 - Set `ignore_first_intervals: <intervalsCount>` option individually per [aggregation config](./configuration/#configuration-file-reference).
  This enables ignoring first `<intervalsCount>` aggregation intervals for that particular aggregation config.
 ## Flush time alignment
 By default, the time for aggregated data flush is aligned by the [`interval`](./configuration/#interval) option.
 For example:
 - if `interval: 1m` is set, then the aggregated data is flushed to the storage at the end of every minute
 - if `interval: 1h` is set, then the aggregated data is flushed to the storage at the end of every hour
 If you do not need such an alignment, then set [`no_align_flush_to_interval:`](./configuration/#no-align-flush-to-interval) `true` option in the [aggregate config](./configuration/#configuration-file-reference).
 In this case aggregated data flushes will be aligned to the `vmagent` start time or to [config reload](./configuration/#configuration-update) time.
 The aggregated data on the first and the last interval is dropped during `vmagent` start, restart or [config reload](./configuration/#configuration-update),
 since the first and the last aggregation intervals are incomplete, so they usually contain incomplete confusing data.
 If you need preserving the aggregated data on these intervals, then set [`flush_on_shutdown:`](./configuration/#flush-on-shutdown) `true` option.
 See also:
 - [Ignore aggregation intervals on start](#ignore-aggregation-intervals-on-start)
 - [Ignoring old samples](#ignoring-old-samples)
 ## Output metric names
 Output metric names for stream aggregation are constructed according to the following pattern:
 ```text
 <metric_name>:<interval>[_by_<by_labels>][_without_<without_labels>]_<output>
 ```
 - `<metric_name>` is the original metric name.
 - `<interval>` is the [`interval`](./configuration/#interval) specified in the [stream aggregation config](./configuration/#configuration-file-reference).
 - `<by_labels>` is `_`-delimited sorted list of [`by`](./configuration/#by) labels.
  If the [`by`](./configuration/#by) list is missing in the config, then the `_by_<by_labels>` part isn't included in the output metric name.
 - `<without_labels>` is an optional `_`-delimited sorted list of [`without`](./configuration/#without) labels specified in the [stream aggregation config](./configuration/#configuration-file-reference).
  If the [`without`](./configuration/#without) list is missing in the config, then the `_without_<without_labels>` part isn't included in the output metric name.
 - `<output>` is the aggregate used for constructing the output metric. The aggregate name is taken from the [`outputs`](./configuration/outputs) list
  at the corresponding [stream aggregation config](./configuration/#configuration-file-reference).
 Both input and output metric names can be modified if needed via relabeling according to [these docs](#relabeling).
 It is possible to leave the original metric name after the aggregation by specifying [`keep_metric_names:`](./configuration/#keep-metric-names) `true` option at [stream aggregation config](./configuration/#configuration-file-reference).
 The [`keep_metric_names`](./configuration/#keep-metric-names) option can be used if only a single output is set in [`outputs`](./configuration/outputs) list.
 ## Relabeling
 It is possible to apply [arbitrary relabeling](https://docs.victoriametrics.com/vmagent#relabeling) to input and output metrics
 during stream aggregation via [`input_relabel_configs`](./configuration/#input-relabel-configs) and [`output_relabel_configs`](./configuration/#output-relabel-configs) options in [stream aggregation config](./configuration/#configuration-file-reference).
 Relabeling rules inside [`input_relabel_configs`](./configuration/#input-relabel-configs) are applied to samples matching the [`match`](./configuration/#match) filters before optional [deduplication](#deduplication).
 Relabeling rules inside [`output_relabel_configs`](./configuration/#output-relabel-configs) are applied to aggregated samples before sending them to the remote storage.
 For example, the following config removes the `:1m_sum_samples` suffix added [to the output metric name](#output-metric-names):
 ```yaml
 - interval: 1m
  outputs: [sum_samples]
  output_relabel_configs:
  - source_labels: [__name__]
    target_label: __name__
    regex: "(.+):.+"
 ```
 Another option to remove the suffix, which is added by stream aggregation, is to add [`keep_metric_names:`](./configuration/#keep-metric-names) `true` to the config:
 ```yaml
 - interval: 1m
  outputs: [sum_samples]
  keep_metric_names: true
 ```
 See also [dropping unneeded labels](#dropping-unneeded-labels).
 ## Dropping unneeded labels
 If you need dropping some labels from input samples before [input relabeling](#relabeling), [de-duplication](#deduplication)
 and stream aggregation, then the following options exist:
 - To specify comma-separated list of label names to drop in `-streamAggr.dropInputLabels` command-line flag
  or via `-remoteWrite.streamAggr.dropInputLabels` individually per each `-remoteWrite.url`.
  For example, `-streamAggr.dropInputLabels=replica,az` instructs to drop `replica` and `az` labels from input samples
  before applying de-duplication and stream aggregation.
 - To specify [`drop_input_labels`](./configuration/#drop-input-labels) list with the labels to drop.
  For example, the following config drops `replica` label from input samples with the name `process_resident_memory_bytes`
  before calculating the average over one minute:
  ```yaml
  - match: process_resident_memory_bytes
    interval: 1m
    drop_input_labels: [replica]
    outputs: [avg]
    keep_metric_names: true
  ```
 Typical use case is to drop `replica` label from samples, which are received from high availability replicas.
 ## Aggregating by labels
 All the labels for the input metrics are preserved by default in the output metrics. For example,
 the input metric `foo{app="bar",instance="host1"}` results to the output metric `foo:1m_sum_samples{app="bar",instance="host1"}`
 when the following [stream aggregation config](./configuration/#configuration-file-reference) is used:
 ```yaml
 - interval: 1m
  outputs: [sum_samples]
 ```
 The input labels can be removed via [`without`](./configuration/#without) list specified in the config. For example, the following config
 removes the `instance` label from output metrics by summing input samples across all the instances:
 ```yaml
 - interval: 1m
  without: [instance]
  outputs: [sum_samples]
 ```
 In this case the `foo{app="bar",instance="..."}` input metrics are transformed into `foo:1m_without_instance_sum_samples{app="bar"}`
 output metric according to [output metric naming](#output-metric-names).
 It is possible specifying the exact list of labels in the output metrics via [`by`](./configuration/#by) list.
 For example, the following config sums input samples by the `app` label:
 ```yaml
 - interval: 1m
  by: [app]
  outputs: [sum_samples]
 ```
 In this case the `foo{app="bar",instance="..."}` input metrics are transformed into `foo:1m_by_app_sum_samples{app="bar"}`
 output metric according to [output metric naming](#output-metric-names).
 The labels used in [`by`](./configuration/#by) and [`without`](./configuration/#without) lists can be modified via [`input_relabel_configs`](./configuration/#input-relabel-configs) section - see [these docs](#relabeling).
 See also [aggregation outputs](./configuration/outputs/).
--- a/docs/stream-aggregation/troubleshooting.md
+++ b/docs/stream-aggregation/troubleshooting.md
@ -0,0 +1,74 @@
 ---
 sort: 5
 weight: 5
 title: Troubleshooting
 menu:
  docs:
    identifier: stream-aggregation-troubleshooting
    parent: 'stream-aggregation'
    weight: 5
 aliases:
 - /stream-aggregation/troubleshooting/
 - /stream-aggregation/troubleshooting/index.html
 ---
 ## Known scenarios
 - [Unexpected spikes for `total` or `increase` outputs](#staleness).
 - [Lower than expected values for `total_prometheus` and `increase_prometheus` outputs](#staleness).
 - [High memory usage and CPU usage](#high-resource-usage).
 - [Unexpected results in vmagent cluster mode](#cluster-mode).
 ### Staleness
 The following outputs track the last seen per-series values in order to properly calculate output values:
 - [rate_sum](./configuration/outputs/#rate_sum)
 - [rate_avg](./configuration/outputs/#rate_avg)
 - [total](./configuration/outputs/#total)
 - [total_prometheus](./configuration/outputs/#total_prometheus)
 - [increase](./configuration/outputs/#increase)
 - [increase_prometheus](./configuration/outputs/#increase_prometheus)
 - [histogram_bucket](./configuration/outputs/#histogram_bucket)
 The last seen per-series value is dropped if no new samples are received for the given time series during two consecutive aggregation
 intervals specified in [stream aggregation config](./configuration/README.md) via `interval` option.
 If a new sample for the existing time series is received after that, then it is treated as the first sample for a new time series.
 This may lead to the following issues:
 - Lower than expected results for [total_prometheus](./configuration/outputs/#total_prometheus) and [increase_prometheus](./configuration/outputs/#increase_prometheus) outputs,
  since they ignore the first sample in a new time series.
 - Unexpected spikes for [total](./configuration/outputs/#total) and [increase](./configuration/outputs/#increase) outputs, since they assume that new time series start from 0.
 These issues can be fixed in the following ways:
 - By increasing the `interval` option at [stream aggregation config](./configuration/README.md), so it covers the expected
  delays in data ingestion pipelines.
 - By specifying the `staleness_interval` option at [stream aggregation config](./configuration/README.md), so it covers the expected
  delays in data ingestion pipelines. By default, the `staleness_interval` equals to `2 x interval`.
 ### High resource usage
 The following solutions can help reducing memory usage and CPU usage durting streaming aggregation:
 - To use more specific `match` filters at [streaming aggregation config](./configuration/README.md), so only the really needed
  [raw samples](https://docs.victoriametrics.com/keyconcepts#raw-samples) are aggregated.
 - To increase aggregation interval by specifying bigger duration for the `interval` option at [streaming aggregation config](./configuration/README.md).
 - To generate lower number of output time series by using less specific [`by` list](#aggregating-by-labels) or more specific [`without` list](#aggregating-by-labels).
 - To drop unneeded long labels in input samples via [input_relabel_configs](#relabeling).
 ### Cluster mode
 If you use [vmagent in cluster mode](https://docs.victoriametrics.com/vmagent#scraping-big-number-of-targets) for streaming aggregation
 then be careful when using [`by` or `without` options](#aggregating-by-labels) or when modifying sample labels
 via [relabeling](#relabeling), since incorrect usage may result in duplicates and data collision.
 For example, if more than one `vmagent` instance calculates [increase](./configuration/outputs/#increase) for `http_requests_total` metric
 with `by: [path]` option, then all the `vmagent` instances will aggregate samples to the same set of time series with different `path` labels.
 The proper fix would be [adding an unique label](https://docs.victoriametrics.com/vmagent#adding-labels-to-metrics) for all the output samples
 produced by each `vmagent`, so they are aggregated into distinct sets of [time series](https://docs.victoriametrics.com/keyconcepts#time-series).
 These time series then can be aggregated later as needed during querying.
 If `vmagent` instances run in Docker or Kubernetes, then you can refer `POD_NAME` or `HOSTNAME` environment variables
 as an unique label value per each `vmagent` via `-remoteWrite.label=vmagent=%{HOSTNAME}` command-line flag.
 See [these docs](https://docs.victoriametrics.com/#environment-variables) on how to refer environment variables in VictoriaMetrics components.
--- a/docs/stream-aggregation/use-cases.md
+++ b/docs/stream-aggregation/use-cases.md
@ -0,0 +1,305 @@
 ---
 sort: 1
 weight: 1
 title: Use cases
 menu:
  docs:
    identifier: stream-aggregation-use-cases
    parent: 'stream-aggregation'
    weight: 1
 aliases:
 - /stream-aggregation/use-cases/
 - /stream-aggregation/use-cases/index.html
 ---
 ## Statsd alternative
 Stream aggregation can be used as [statsd](https://github.com/statsd/statsd) alternative in the following cases:
 * [Counting input samples](#counting-input-samples)
 * [Summing input metrics](#summing-input-metrics)
 * [Quantiles over input metrics](#quantiles-over-input-metrics)
 * [Histograms over input metrics](#histograms-over-input-metrics)
 * [Aggregating histograms](#aggregating-histograms)
 Currently, streaming aggregation is available only for [supported data ingestion protocols](https://docs.victoriametrics.com/#how-to-import-time-series-data)
 and not available for [Statsd metrics format](https://github.com/statsd/statsd/blob/master/docs/metric_types.md).
 ## Recording rules alternative
 Sometimes [alerting queries](https://docs.victoriametrics.com/vmalert#alerting-rules) may require non-trivial amounts of CPU, RAM,
 disk IO and network bandwidth at metrics storage side. For example, if `http_request_duration_seconds` histogram is generated by thousands
 of application instances, then the alerting query `histogram_quantile(0.99, sum(increase(http_request_duration_seconds_bucket[5m])) without (instance)) > 0.5`
 can become slow, since it needs to scan too big number of unique [time series](https://docs.victoriametrics.com/keyconcepts#time-series)
 with `http_request_duration_seconds_bucket` name. This alerting query can be accelerated by pre-calculating
 the `sum(increase(http_request_duration_seconds_bucket[5m])) without (instance)` via [recording rule](https://docs.victoriametrics.com/vmalert#recording-rules).
 But this recording rule may take too much time to execute too. In this case the slow recording rule can be substituted
 with the following [stream aggregation config](./configuration/#configuration-file-reference):
 ```yaml
 - match: 'http_request_duration_seconds_bucket'
  interval: 5m
  without: [instance]
  outputs: [total]
 ```
 This stream aggregation generates `http_request_duration_seconds_bucket:5m_without_instance_total` output series according to [output metric naming](./key-concepts.md#output-metric-names).
 Then these series can be used in [alerting rules](https://docs.victoriametrics.com/vmalert#alerting-rules):
 ```metricsql
 histogram_quantile(0.99, last_over_time(http_request_duration_seconds_bucket:5m_without_instance_total[5m])) > 0.5
 ```
 This query is executed much faster than the original query, because it needs to scan much lower number of time series.
 See [the list of aggregate output](./configuration/outputs), which can be specified at `output` field.
 See also [aggregating by labels](./key-concepts.md/#aggregating-by-labels).
 Field `interval` is recommended to be set to a value at least several times higher than your metrics collect interval.
 ## Reducing the number of stored samples
 If per-[series](https://docs.victoriametrics.com/keyconcepts#time-series) samples are ingested at high frequency,
 then this may result in high disk space usage, since too much data must be stored to disk. This also may result
 in slow queries, since too much data must be processed during queries.
 This can be fixed with the stream aggregation by increasing the interval between per-series samples stored in the database.
 For example, the following [stream aggregation config](./configuration/#configuration-file-reference) reduces the frequency of input samples
 to one sample per 5 minutes per each input time series (this operation is also known as downsampling):
 ```yaml
  # Aggregate metrics ending with _total with `total` output.
  # See {{% ref "./configuration/outputs" %}}
 - match: '{__name__=~".+_total"}'
  interval: 5m
  outputs: [total]
  # Downsample other metrics with `count_samples`, `sum_samples`, `min` and `max` outputs
  # See {{% ref "./configuration/outputs" %}}
 - match: '{__name__!~".+_total"}'
  interval: 5m
  outputs: [count_samples, sum_samples, min, max]
 ```
 The aggregated output metrics have the following names according to [output metric naming](./key-concepts.md#output-metric-names):
 ```text
 # For input metrics ending with _total
 some_metric_total:5m_total
 # For input metrics not ending with _total
 some_metric:5m_count_samples
 some_metric:5m_sum_samples
 some_metric:5m_min
 some_metric:5m_max
 ```
 See [the list of aggregate output](./configuration/outputs), which can be specified at `output` field.
 See also [aggregating histograms](#aggregating-histograms) and [aggregating by labels](./key-concepts.md#aggregating-by-labels).
 ## Reducing the number of stored series
 Sometimes applications may generate too many [time series](https://docs.victoriametrics.com/keyconcepts#time-series).
 For example, the `http_requests_total` metric may have `path` or `user` label with too big number of unique values.
 In this case the following stream aggregation can be used for reducing the number metrics stored in VictoriaMetrics:
 ```yaml
 - match: 'http_requests_total'
  interval: 30s
  without: [path, user]
  outputs: [total]
 ```
 This config specifies labels, which must be removed from the aggregate output, in the `without` list.
 See [these docs](./key-concepts.md#aggregating-by-labels) for more details.
 The aggregated output metric has the following name according to [output metric naming](./key-concepts.md#output-metric-names):
 ```text
 http_requests_total:30s_without_path_user_total
 ```
 See [the list of aggregate output](./configuration/outputs), which can be specified at `output` field.
 See also [aggregating histograms](#aggregating-histograms).
 ## Counting input samples
 If the monitored application generates event-based metrics, then it may be useful to count the number of such metrics
 at stream aggregation level.
 For example, if an advertising server generates `hits{some="labels"} 1` and `clicks{some="labels"} 1` metrics
 per each incoming hit and click, then the following [stream aggregation config](./configuration/#configuration-file-reference)
 can be used for counting these metrics per 30 second interval:
 ```yaml
 - match: '{__name__=~"hits|clicks"}'
  interval: 30s
  outputs: [count_samples]
 ```
 This config generates the following output metrics for `hits` and `clicks` input metrics
 according to [output metric naming](./key-concepts.md#output-metric-names):
 ```text
 hits:30s_count_samples count1
 clicks:30s_count_samples count2
 ```
 See [the list of aggregate output](./configuration/outputs), which can be specified at `output` field.
 See also [aggregating by labels](./key-concepts.md#aggregating-by-labels).
 ## Summing input metrics
 If the monitored application calculates some events and then sends the calculated number of events to VictoriaMetrics
 at irregular intervals or at too high frequency, then stream aggregation can be used for summing such events
 and writing the aggregate sums to the storage at regular intervals.
 For example, if an advertising server generates `hits{some="labels} N` and `clicks{some="labels"} M` metrics
 at irregular intervals, then the following [stream aggregation config](./configuration/#configuration-file-reference)
 can be used for summing these metrics per minute:
 ```yaml
 - match: '{__name__=~"hits|clicks"}'
  interval: 1m
  outputs: [sum_samples]
 ```
 This config generates the following output metrics according to [output metric naming](https://docs.victoriametrics.com/keyconcepts#output-metric-names):
 ```text
 hits:1m_sum_samples sum1
 clicks:1m_sum_samples sum2
 ```
 See [the list of aggregate output](./configuration/outputs), which can be specified at `output` field.
 See also [aggregating by labels](./key-concepts.md#aggregating-by-labels).
 ## Quantiles over input metrics
 If the monitored application generates measurement metrics per request, then it may be useful to calculate
 the pre-defined set of [percentiles](https://en.wikipedia.org/wiki/Percentile) over these measurements.
 For example, if the monitored application generates `request_duration_seconds N` and `response_size_bytes M` metrics
 per each incoming request, then the following [stream aggregation config](./configuration/#configuration-file-reference)
 can be used for calculating 50th and 99th percentiles for these metrics every 30 seconds:
 ```yaml
 - match:
  - request_duration_seconds
  - response_size_bytes
  interval: 30s
  outputs: ["quantiles(0.50, 0.99)"]
 ```
 This config generates the following output metrics according to [output metric naming](./key-concepts.md#output-metric-names):
 ```text
 request_duration_seconds:30s_quantiles{quantile="0.50"} value1
 request_duration_seconds:30s_quantiles{quantile="0.99"} value2
 response_size_bytes:30s_quantiles{quantile="0.50"} value1
 response_size_bytes:30s_quantiles{quantile="0.99"} value2
 ```
 See [the list of aggregate output](./configuration/outputs), which can be specified at `output` field.
 See also [histograms over input metrics](#histograms-over-input-metrics) and [aggregating by labels](./key-concepts.md#aggregating-by-labels).
 ## Histograms over input metrics
 If the monitored application generates measurement metrics per request, then it may be useful to calculate
 a [histogram](https://docs.victoriametrics.com/keyconcepts#histogram) over these metrics.
 For example, if the monitored application generates `request_duration_seconds N` and `response_size_bytes M` metrics
 per each incoming request, then the following [stream aggregation config](./configuration/#configuration-file-reference)
 can be used for calculating [VictoriaMetrics histogram buckets](https://valyala.medium.com/improving-histogram-usability-for-prometheus-and-grafana-bc7e5df0e350)
 for these metrics every 60 seconds:
 ```yaml
 - match:
  - request_duration_seconds
  - response_size_bytes
  interval: 60s
  outputs: [histogram_bucket]
 ```
 This config generates the following output metrics according to [output metric naming](./key-concepts.md#output-metric-names).
 ```text
 request_duration_seconds:60s_histogram_bucket{vmrange="start1...end1"} count1
 request_duration_seconds:60s_histogram_bucket{vmrange="start2...end2"} count2
 ...
 request_duration_seconds:60s_histogram_bucket{vmrange="startN...endN"} countN
 response_size_bytes:60s_histogram_bucket{vmrange="start1...end1"} count1
 response_size_bytes:60s_histogram_bucket{vmrange="start2...end2"} count2
 ...
 response_size_bytes:60s_histogram_bucket{vmrange="startN...endN"} countN
 ```
 The resulting histogram buckets can be queried with [MetricsQL](https://docs.victoriametrics.com/metricsql/) in the following ways:
 1. An estimated 50th and 99th [percentiles](https://en.wikipedia.org/wiki/Percentile) of the request duration over the last hour:
   ```metricsql
   histogram_quantiles("quantile", 0.50, 0.99, sum(increase(request_duration_seconds:60s_histogram_bucket[1h])) by (vmrange))
   ```
   This query uses [histogram_quantiles](https://docs.victoriametrics.com/metricsql/#histogram_quantiles) function.
 1. An estimated [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the request duration over the last hour:
   ```metricsql
   histogram_stddev(sum(increase(request_duration_seconds:60s_histogram_bucket[1h])) by (vmrange))
   ```
   This query uses [histogram_stddev](https://docs.victoriametrics.com/metricsql/#histogram_stddev) function.
 1. An estimated share of requests with the duration smaller than `0.5s` over the last hour:
   ```metricsql
   histogram_share(0.5, sum(increase(request_duration_seconds:60s_histogram_bucket[1h])) by (vmrange))
   ```
   This query uses [histogram_share](https://docs.victoriametrics.com/metricsql/#histogram_share) function.
 See [the list of aggregate output](./configuration/outputs), which can be specified at `output` field.
 See also [quantiles over input metrics](#quantiles-over-input-metrics) and [aggregating by labels](./key-concepts.md#aggregating-by-labels).
 ## Aggregating histograms
 [Histogram](https://docs.victoriametrics.com/keyconcepts#histogram) is a set of [counter](https://docs.victoriametrics.com/keyconcepts#counter)
 metrics with different `vmrange` or `le` labels. As they're counters, the applicable aggregation output is
 [total](./configuration/outputs/#total):
 ```yaml
 - match: 'http_request_duration_seconds_bucket'
  interval: 1m
  without: [instance]
  outputs: [total]
 ```
 This config generates the following output metrics according to [output metric naming](./key-concepts.md#output-metric-names):
 ```text
 http_request_duration_seconds_bucket:1m_without_instance_total{le="0.1"} value1
 http_request_duration_seconds_bucket:1m_without_instance_total{le="0.2"} value2
 http_request_duration_seconds_bucket:1m_without_instance_total{le="0.4"} value3
 http_request_duration_seconds_bucket:1m_without_instance_total{le="1"}   value4
 http_request_duration_seconds_bucket:1m_without_instance_total{le="3"}   value5
 http_request_duration_seconds_bucket:1m_without_instance_total{le="+Inf" value6
 ```
 The resulting metrics can be passed to [histogram_quantile](https://docs.victoriametrics.com/metricsql#histogram_quantile)
 function:
 ```metricsql
 histogram_quantile(0.9, sum(rate(http_request_duration_seconds_bucket:1m_without_instance_total[5m])) by(le))
 ```
 Please note, histograms can be aggregated if their `le` labels are configured identically.
 [VictoriaMetrics histogram buckets](https://valyala.medium.com/improving-histogram-usability-for-prometheus-and-grafana-bc7e5df0e350)
 have no such requirement.
 See [the list of aggregate output](./configuration/outputs), which can be specified at `output` field.
 See also [histograms over input metrics](#histograms-over-input-metrics) and [quantiles over input metrics](#quantiles-over-input-metrics).
--- a/docs/vmagent.md
+++ b/docs/vmagent.md
@ -153,7 +153,7 @@ See [these docs](#how-to-collect-metrics-in-prometheus-format) for details.
 `vmagent` can be used as an alternative to [statsd](https://github.com/statsd/statsd)
 when [stream aggregation](https://docs.victoriametrics.com/stream-aggregation/) is enabled.
-See [these docs](https://docs.victoriametrics.com/stream-aggregation/#statsd-alternative) for details.
+See [these docs](https://docs.victoriametrics.com/stream-aggregation/key-concepts#statsd-alternative) for details.
 ### Flexible metrics relay
@ -263,10 +263,10 @@ There is also support for multitenant writes. See [these docs](#multitenancy).
 ### Flexible deduplication
-[Deduplication at stream aggregation](https://docs.victoriametrics.com/stream-aggregation/#deduplication) allows setting up arbitrary complex de-duplication schemes
+[Deduplication at stream aggregation](https://docs.victoriametrics.com/stream-aggregation/key-concepts#deduplication) allows setting up arbitrary complex de-duplication schemes
 for the collected samples. Examples:
- The following command instructs `vmagent` to send only the last sample per each seen [time series](https://docs.victoriametrics.com/keyconcepts/#time-series) per every 60 seconds:
+- The following command instructs `vmagent` to send only the last sample per each seen [time series](https://docs.victoriametrics.com/keyconcepts/#time-series) every 60 seconds:
  ```
  ./vmagent -remoteWrite.url=http://remote-storage/api/v1/write -remoteWrite.streamAggr.dedupInterval=60s
  ```
@ -2199,7 +2199,7 @@ See the docs at https://docs.victoriametrics.com/vmagent/ .
     Supports an array of values separated by comma or specified via multiple flags.
     Value can contain comma inside single-quoted or double-quoted string, {}, [] and () braces.
  -remoteWrite.streamAggr.dedupInterval array
-     Input samples are de-duplicated with this interval before optional aggregation with -remoteWrite.streamAggr.config at the corresponding -remoteWrite.url. See also -dedup.minScrapeInterval and https://docs.victoriametrics.com/stream-aggregation/#deduplication (default 0s)
+     Input samples are de-duplicated with this interval before optional aggregation with -remoteWrite.streamAggr.config at the corresponding -remoteWrite.url. See also -dedup.minScrapeInterval and https://docs.victoriametrics.com/stream-aggregation/key-concepts#deduplication (default 0s)
     Supports array of values separated by comma or specified via multiple flags.
     Empty values are set to default value.
  -remoteWrite.streamAggr.dropInput array
@ -2207,13 +2207,13 @@ See the docs at https://docs.victoriametrics.com/vmagent/ .
     Supports array of values separated by comma or specified via multiple flags.
     Empty values are set to false.
  -remoteWrite.streamAggr.dropInputLabels array
-     An optional list of labels to drop from samples before stream de-duplication and aggregation with -remoteWrite.streamAggr.config and -remoteWrite.streamAggr.dedupInterval at the corresponding -remoteWrite.url. See https://docs.victoriametrics.com/stream-aggregation/#dropping-unneeded-labels
+     An optional list of labels to drop from samples before stream de-duplication and aggregation with -remoteWrite.streamAggr.config and -remoteWrite.streamAggr.dedupInterval at the corresponding -remoteWrite.url. See https://docs.victoriametrics.com/stream-aggregation/key-concepts#dropping-unneeded-labels
     Supports an array of values separated by comma or specified via multiple flags.
     Value can contain comma inside single-quoted or double-quoted string, {}, [] and () braces.
  -remoteWrite.streamAggr.ignoreFirstIntervals array
-     Number of aggregation intervals to skip after the start for the corresponding -remoteWrite.streamAggr.config at the corresponding -remoteWrite.url. Increase this value if you observe incorrect aggregation results after vmagent restarts. It could be caused by receiving bufferred delayed data from clients pushing data into the vmagent. See https://docs.victoriametrics.com/stream-aggregation/#ignore-aggregation-intervals-on-start
+     Number of aggregation intervals to skip after the start for the corresponding -remoteWrite.streamAggr.config at the corresponding -remoteWrite.url. Increase this value if you observe incorrect aggregation results after vmagent restarts. It could be caused by receiving bufferred delayed data from clients pushing data into the vmagent. See https://docs.victoriametrics.com/stream-aggregation/key-concepts#ignore-aggregation-intervals-on-start
  -remoteWrite.streamAggr.ignoreOldSamples array
-     Whether to ignore input samples with old timestamps outside the current aggregation interval for the corresponding -remoteWrite.streamAggr.config at the corresponding -remoteWrite.url. See https://docs.victoriametrics.com/stream-aggregation/#ignoring-old-samples
+     Whether to ignore input samples with old timestamps outside the current aggregation interval for the corresponding -remoteWrite.streamAggr.config at the corresponding -remoteWrite.url. See https://docs.victoriametrics.com/stream-aggregation/key-concepts#ignoring-old-samples
     Supports array of values separated by comma or specified via multiple flags.
     Empty values are set to false.
  -remoteWrite.streamAggr.keepInput array
@ -2261,18 +2261,18 @@ See the docs at https://docs.victoriametrics.com/vmagent/ .
  -streamAggr.config string
    Optional path to file with stream aggregation config. See https://docs.victoriametrics.com/stream-aggregation/ . See also -streamAggr.keepInput, -streamAggr.dropInput and -streamAggr.dedupInterval
  -streamAggr.dedupInterval value
-    Input samples are de-duplicated with this interval on aggregator before optional aggregation with -streamAggr.config . See also -dedup.minScrapeInterval and https://docs.victoriametrics.com/stream-aggregation/#deduplication
+    Input samples are de-duplicated with this interval on aggregator before optional aggregation with -streamAggr.config . See also -dedup.minScrapeInterval and https://docs.victoriametrics.com/stream-aggregation/key-concepts#deduplication
    The following optional suffixes are supported: s (second), m (minute), h (hour), d (day), w (week), y (year). If suffix isn't set, then the duration is counted in months (default 0s)
  -streamAggr.dropInput
    Whether to drop all the input samples after the aggregation with -remoteWrite.streamAggr.config. By default, only aggregates samples are dropped, while the remaining samples are written to remote storages write. See also -streamAggr.keepInput and https://docs.victoriametrics.com/stream-aggregation/
  -streamAggr.dropInputLabels array
-    An optional list of labels to drop from samples for aggregator before stream de-duplication and aggregation . See https://docs.victoriametrics.com/stream-aggregation/#dropping-unneeded-labels
+    An optional list of labels to drop from samples for aggregator before stream de-duplication and aggregation . See https://docs.victoriametrics.com/stream-aggregation/key-concepts#dropping-unneeded-labels
    Supports an array of values separated by comma or specified via multiple flags.
    Value can contain comma inside single-quoted or double-quoted string, {}, [] and () braces.
  -streamAggr.ignoreFirstIntervals int
-    Number of aggregation intervals to skip after the start for aggregator. Increase this value if you observe incorrect aggregation results after vmagent restarts. It could be caused by receiving unordered delayed data from clients pushing data into the vmagent. See https://docs.victoriametrics.com/stream-aggregation/#ignore-aggregation-intervals-on-start
+    Number of aggregation intervals to skip after the start for aggregator. Increase this value if you observe incorrect aggregation results after vmagent restarts. It could be caused by receiving unordered delayed data from clients pushing data into the vmagent. See https://docs.victoriametrics.com/stream-aggregation/key-concepts#ignore-aggregation-intervals-on-start
  -streamAggr.ignoreOldSamples
-    Whether to ignore input samples with old timestamps outside the current aggregation interval for aggregator. See https://docs.victoriametrics.com/stream-aggregation/#ignoring-old-samples
+    Whether to ignore input samples with old timestamps outside the current aggregation interval for aggregator. See https://docs.victoriametrics.com/stream-aggregation/key-concepts#ignoring-old-samples
  -streamAggr.keepInput
    Whether to keep all the input samples after the aggregation with -streamAggr.config. By default, only aggregates samples are dropped, while the remaining samples are written to remote storages write. See also -streamAggr.dropInput and https://docs.victoriametrics.com/stream-aggregation/
  -tls array