From e094c8e21465f1cc49558f8e1b7c60512dc7fd62 Mon Sep 17 00:00:00 2001 From: Aliaksandr Valialkin Date: Tue, 28 Mar 2023 17:00:14 -0700 Subject: [PATCH] docs: mention that VictoriaMetrics rounds time range to UTC days at /api/v1/labels, /api/v1/label/.../values and /api/v1/series handlers Updates https://github.com/VictoriaMetrics/VictoriaMetrics/issues/3107 --- README.md | 41 +++++++++++++++++++++------ docs/README.md | 41 +++++++++++++++++++++------ docs/Single-server-VictoriaMetrics.md | 41 +++++++++++++++++++++------ docs/url-examples.md | 9 ++++-- docs/vmagent.md | 2 +- 5 files changed, 106 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 931aecfb9..ff78de46e 100644 --- a/README.md +++ b/README.md @@ -742,20 +742,45 @@ All the Prometheus querying API handlers can be prepended with `/prometheus` pre ### Prometheus querying API enhancements -VictoriaMetrics accepts optional `extra_label==` query arg, which can be used for enforcing additional label filters for queries. For example, -`/api/v1/query_range?extra_label=user_id=123&extra_label=group_id=456&query=` would automatically add `{user_id="123",group_id="456"}` label filters to the given ``. This functionality can be used for limiting the scope of time series visible to the given tenant. It is expected that the `extra_label` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. +VictoriaMetrics accepts optional `extra_label==` query arg, which can be used +for enforcing additional label filters for queries. For example, `/api/v1/query_range?extra_label=user_id=123&extra_label=group_id=456&query=` +would automatically add `{user_id="123",group_id="456"}` label filters to the given ``. +This functionality can be used for limiting the scope of time series visible to the given tenant. +It is expected that the `extra_label` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. +See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. -VictoriaMetrics accepts optional `extra_filters[]=series_selector` query arg, which can be used for enforcing arbitrary label filters for queries. For example, -`/api/v1/query_range?extra_filters[]={env=~"prod|staging",user="xyz"}&query=` would automatically add `{env=~"prod|staging",user="xyz"}` label filters to the given ``. This functionality can be used for limiting the scope of time series visible to the given tenant. It is expected that the `extra_filters[]` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. +VictoriaMetrics accepts optional `extra_filters[]=series_selector` query arg, which can be used for enforcing arbitrary label filters for queries. +For example, `/api/v1/query_range?extra_filters[]={env=~"prod|staging",user="xyz"}&query=` would automatically +add `{env=~"prod|staging",user="xyz"}` label filters to the given ``. This functionality can be used for limiting +the scope of time series visible to the given tenant. It is expected that the `extra_filters[]` query args are automatically +set by auth proxy sitting in front of VictoriaMetrics. +See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. VictoriaMetrics accepts multiple formats for `time`, `start` and `end` query args - see [these docs](#timestamp-formats). -VictoriaMetrics accepts `round_digits` query arg for `/api/v1/query` and `/api/v1/query_range` handlers. It can be used for rounding response values to the given number of digits after the decimal point. For example, `/api/v1/query?query=avg_over_time(temperature[1h])&round_digits=2` would round response values to up to two digits after the decimal point. +VictoriaMetrics accepts `round_digits` query arg for [/api/v1/query](https://docs.victoriametrics.com/keyConcepts.html#instant-query) +and [/api/v1/query_range](https://docs.victoriametrics.com/keyConcepts.html#range-query) handlers. It can be used for rounding response values +to the given number of digits after the decimal point. +For example, `/api/v1/query?query=avg_over_time(temperature[1h])&round_digits=2` would round response values to up to two digits after the decimal point. -VictoriaMetrics accepts `limit` query arg for `/api/v1/labels` and `/api/v1/label//values` handlers for limiting the number of returned entries. For example, the query to `/api/v1/labels?limit=5` returns a sample of up to 5 unique labels, while ignoring the rest of labels. If the provided `limit` value exceeds the corresponding `-search.maxTagKeys` / `-search.maxTagValues` command-line flag values, then limits specified in the command-line flags are used. +VictoriaMetrics accepts `limit` query arg for [/api/v1/labels](https://docs.victoriametrics.com/url-examples.html#apiv1labels) +and [`/api/v1/label//values`](https://docs.victoriametrics.com/url-examples.html#apiv1labelvalues) handlers for limiting the number of returned entries. +For example, the query to `/api/v1/labels?limit=5` returns a sample of up to 5 unique labels, while ignoring the rest of labels. +If the provided `limit` value exceeds the corresponding `-search.maxTagKeys` / `-search.maxTagValues` command-line flag values, +then limits specified in the command-line flags are used. -By default, VictoriaMetrics returns time series for the last 5 minutes from `/api/v1/series`, `/api/v1/labels` and `/api/v1/label//values` while the Prometheus API defaults to all time. Explicitly set `start` and `end` to select the desired time range. -VictoriaMetrics accepts `limit` query arg for `/api/v1/series` handlers for limiting the number of returned entries. For example, the query to `/api/v1/series?limit=5` returns a sample of up to 5 series, while ignoring the rest. If the provided `limit` value exceeds the corresponding `-search.maxSeries` command-line flag values, then limits specified in the command-line flags are used. +By default, VictoriaMetrics returns time series for the last day starting at 00:00 UTC +from [/api/v1/series](https://docs.victoriametrics.com/url-examples.html#apiv1series), +[/api/v1/labels](https://docs.victoriametrics.com/url-examples.html#apiv1labels) and +[`/api/v1/label//values`](https://docs.victoriametrics.com/url-examples.html#apiv1labelvalues), +while the Prometheus API defaults to all time. Explicitly set `start` and `end` to select the desired time range. +VictoriaMetrics rounds the specified `start..end` time range to day granularity because of performance optimization concerns. +If you need the exact set of label names and label values on the given time range, then send queries +to [/api/v1/query](https://docs.victoriametrics.com/keyConcepts.html#instant-query) or to [/api/v1/query_range](https://docs.victoriametrics.com/keyConcepts.html#range-query). + +VictoriaMetrics accepts `limit` query arg at [/api/v1/series](https://docs.victoriametrics.com/url-examples.html#apiv1series) +for limiting the number of returned entries. For example, the query to `/api/v1/series?limit=5` returns a sample of up to 5 series, while ignoring the rest of series. +If the provided `limit` value exceeds the corresponding `-search.maxSeries` command-line flag values, then limits specified in the command-line flags are used. Additionally, VictoriaMetrics provides the following handlers: diff --git a/docs/README.md b/docs/README.md index 7817851bd..52ff491d1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -743,20 +743,45 @@ All the Prometheus querying API handlers can be prepended with `/prometheus` pre ### Prometheus querying API enhancements -VictoriaMetrics accepts optional `extra_label==` query arg, which can be used for enforcing additional label filters for queries. For example, -`/api/v1/query_range?extra_label=user_id=123&extra_label=group_id=456&query=` would automatically add `{user_id="123",group_id="456"}` label filters to the given ``. This functionality can be used for limiting the scope of time series visible to the given tenant. It is expected that the `extra_label` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. +VictoriaMetrics accepts optional `extra_label==` query arg, which can be used +for enforcing additional label filters for queries. For example, `/api/v1/query_range?extra_label=user_id=123&extra_label=group_id=456&query=` +would automatically add `{user_id="123",group_id="456"}` label filters to the given ``. +This functionality can be used for limiting the scope of time series visible to the given tenant. +It is expected that the `extra_label` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. +See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. -VictoriaMetrics accepts optional `extra_filters[]=series_selector` query arg, which can be used for enforcing arbitrary label filters for queries. For example, -`/api/v1/query_range?extra_filters[]={env=~"prod|staging",user="xyz"}&query=` would automatically add `{env=~"prod|staging",user="xyz"}` label filters to the given ``. This functionality can be used for limiting the scope of time series visible to the given tenant. It is expected that the `extra_filters[]` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. +VictoriaMetrics accepts optional `extra_filters[]=series_selector` query arg, which can be used for enforcing arbitrary label filters for queries. +For example, `/api/v1/query_range?extra_filters[]={env=~"prod|staging",user="xyz"}&query=` would automatically +add `{env=~"prod|staging",user="xyz"}` label filters to the given ``. This functionality can be used for limiting +the scope of time series visible to the given tenant. It is expected that the `extra_filters[]` query args are automatically +set by auth proxy sitting in front of VictoriaMetrics. +See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. VictoriaMetrics accepts multiple formats for `time`, `start` and `end` query args - see [these docs](#timestamp-formats). -VictoriaMetrics accepts `round_digits` query arg for `/api/v1/query` and `/api/v1/query_range` handlers. It can be used for rounding response values to the given number of digits after the decimal point. For example, `/api/v1/query?query=avg_over_time(temperature[1h])&round_digits=2` would round response values to up to two digits after the decimal point. +VictoriaMetrics accepts `round_digits` query arg for [/api/v1/query](https://docs.victoriametrics.com/keyConcepts.html#instant-query) +and [/api/v1/query_range](https://docs.victoriametrics.com/keyConcepts.html#range-query) handlers. It can be used for rounding response values +to the given number of digits after the decimal point. +For example, `/api/v1/query?query=avg_over_time(temperature[1h])&round_digits=2` would round response values to up to two digits after the decimal point. -VictoriaMetrics accepts `limit` query arg for `/api/v1/labels` and `/api/v1/label//values` handlers for limiting the number of returned entries. For example, the query to `/api/v1/labels?limit=5` returns a sample of up to 5 unique labels, while ignoring the rest of labels. If the provided `limit` value exceeds the corresponding `-search.maxTagKeys` / `-search.maxTagValues` command-line flag values, then limits specified in the command-line flags are used. +VictoriaMetrics accepts `limit` query arg for [/api/v1/labels](https://docs.victoriametrics.com/url-examples.html#apiv1labels) +and [`/api/v1/label//values`](https://docs.victoriametrics.com/url-examples.html#apiv1labelvalues) handlers for limiting the number of returned entries. +For example, the query to `/api/v1/labels?limit=5` returns a sample of up to 5 unique labels, while ignoring the rest of labels. +If the provided `limit` value exceeds the corresponding `-search.maxTagKeys` / `-search.maxTagValues` command-line flag values, +then limits specified in the command-line flags are used. -By default, VictoriaMetrics returns time series for the last 5 minutes from `/api/v1/series`, `/api/v1/labels` and `/api/v1/label//values` while the Prometheus API defaults to all time. Explicitly set `start` and `end` to select the desired time range. -VictoriaMetrics accepts `limit` query arg for `/api/v1/series` handlers for limiting the number of returned entries. For example, the query to `/api/v1/series?limit=5` returns a sample of up to 5 series, while ignoring the rest. If the provided `limit` value exceeds the corresponding `-search.maxSeries` command-line flag values, then limits specified in the command-line flags are used. +By default, VictoriaMetrics returns time series for the last day starting at 00:00 UTC +from [/api/v1/series](https://docs.victoriametrics.com/url-examples.html#apiv1series), +[/api/v1/labels](https://docs.victoriametrics.com/url-examples.html#apiv1labels) and +[`/api/v1/label//values`](https://docs.victoriametrics.com/url-examples.html#apiv1labelvalues), +while the Prometheus API defaults to all time. Explicitly set `start` and `end` to select the desired time range. +VictoriaMetrics rounds the specified `start..end` time range to day granularity because of performance optimization concerns. +If you need the exact set of label names and label values on the given time range, then send queries +to [/api/v1/query](https://docs.victoriametrics.com/keyConcepts.html#instant-query) or to [/api/v1/query_range](https://docs.victoriametrics.com/keyConcepts.html#range-query). + +VictoriaMetrics accepts `limit` query arg at [/api/v1/series](https://docs.victoriametrics.com/url-examples.html#apiv1series) +for limiting the number of returned entries. For example, the query to `/api/v1/series?limit=5` returns a sample of up to 5 series, while ignoring the rest of series. +If the provided `limit` value exceeds the corresponding `-search.maxSeries` command-line flag values, then limits specified in the command-line flags are used. Additionally, VictoriaMetrics provides the following handlers: diff --git a/docs/Single-server-VictoriaMetrics.md b/docs/Single-server-VictoriaMetrics.md index 625d67898..a9f13a957 100644 --- a/docs/Single-server-VictoriaMetrics.md +++ b/docs/Single-server-VictoriaMetrics.md @@ -746,20 +746,45 @@ All the Prometheus querying API handlers can be prepended with `/prometheus` pre ### Prometheus querying API enhancements -VictoriaMetrics accepts optional `extra_label==` query arg, which can be used for enforcing additional label filters for queries. For example, -`/api/v1/query_range?extra_label=user_id=123&extra_label=group_id=456&query=` would automatically add `{user_id="123",group_id="456"}` label filters to the given ``. This functionality can be used for limiting the scope of time series visible to the given tenant. It is expected that the `extra_label` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. +VictoriaMetrics accepts optional `extra_label==` query arg, which can be used +for enforcing additional label filters for queries. For example, `/api/v1/query_range?extra_label=user_id=123&extra_label=group_id=456&query=` +would automatically add `{user_id="123",group_id="456"}` label filters to the given ``. +This functionality can be used for limiting the scope of time series visible to the given tenant. +It is expected that the `extra_label` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. +See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. -VictoriaMetrics accepts optional `extra_filters[]=series_selector` query arg, which can be used for enforcing arbitrary label filters for queries. For example, -`/api/v1/query_range?extra_filters[]={env=~"prod|staging",user="xyz"}&query=` would automatically add `{env=~"prod|staging",user="xyz"}` label filters to the given ``. This functionality can be used for limiting the scope of time series visible to the given tenant. It is expected that the `extra_filters[]` query args are automatically set by auth proxy sitting in front of VictoriaMetrics. See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. +VictoriaMetrics accepts optional `extra_filters[]=series_selector` query arg, which can be used for enforcing arbitrary label filters for queries. +For example, `/api/v1/query_range?extra_filters[]={env=~"prod|staging",user="xyz"}&query=` would automatically +add `{env=~"prod|staging",user="xyz"}` label filters to the given ``. This functionality can be used for limiting +the scope of time series visible to the given tenant. It is expected that the `extra_filters[]` query args are automatically +set by auth proxy sitting in front of VictoriaMetrics. +See [vmauth](https://docs.victoriametrics.com/vmauth.html) and [vmgateway](https://docs.victoriametrics.com/vmgateway.html) as examples of such proxies. VictoriaMetrics accepts multiple formats for `time`, `start` and `end` query args - see [these docs](#timestamp-formats). -VictoriaMetrics accepts `round_digits` query arg for `/api/v1/query` and `/api/v1/query_range` handlers. It can be used for rounding response values to the given number of digits after the decimal point. For example, `/api/v1/query?query=avg_over_time(temperature[1h])&round_digits=2` would round response values to up to two digits after the decimal point. +VictoriaMetrics accepts `round_digits` query arg for [/api/v1/query](https://docs.victoriametrics.com/keyConcepts.html#instant-query) +and [/api/v1/query_range](https://docs.victoriametrics.com/keyConcepts.html#range-query) handlers. It can be used for rounding response values +to the given number of digits after the decimal point. +For example, `/api/v1/query?query=avg_over_time(temperature[1h])&round_digits=2` would round response values to up to two digits after the decimal point. -VictoriaMetrics accepts `limit` query arg for `/api/v1/labels` and `/api/v1/label//values` handlers for limiting the number of returned entries. For example, the query to `/api/v1/labels?limit=5` returns a sample of up to 5 unique labels, while ignoring the rest of labels. If the provided `limit` value exceeds the corresponding `-search.maxTagKeys` / `-search.maxTagValues` command-line flag values, then limits specified in the command-line flags are used. +VictoriaMetrics accepts `limit` query arg for [/api/v1/labels](https://docs.victoriametrics.com/url-examples.html#apiv1labels) +and [`/api/v1/label//values`](https://docs.victoriametrics.com/url-examples.html#apiv1labelvalues) handlers for limiting the number of returned entries. +For example, the query to `/api/v1/labels?limit=5` returns a sample of up to 5 unique labels, while ignoring the rest of labels. +If the provided `limit` value exceeds the corresponding `-search.maxTagKeys` / `-search.maxTagValues` command-line flag values, +then limits specified in the command-line flags are used. -By default, VictoriaMetrics returns time series for the last 5 minutes from `/api/v1/series`, `/api/v1/labels` and `/api/v1/label//values` while the Prometheus API defaults to all time. Explicitly set `start` and `end` to select the desired time range. -VictoriaMetrics accepts `limit` query arg for `/api/v1/series` handlers for limiting the number of returned entries. For example, the query to `/api/v1/series?limit=5` returns a sample of up to 5 series, while ignoring the rest. If the provided `limit` value exceeds the corresponding `-search.maxSeries` command-line flag values, then limits specified in the command-line flags are used. +By default, VictoriaMetrics returns time series for the last day starting at 00:00 UTC +from [/api/v1/series](https://docs.victoriametrics.com/url-examples.html#apiv1series), +[/api/v1/labels](https://docs.victoriametrics.com/url-examples.html#apiv1labels) and +[`/api/v1/label//values`](https://docs.victoriametrics.com/url-examples.html#apiv1labelvalues), +while the Prometheus API defaults to all time. Explicitly set `start` and `end` to select the desired time range. +VictoriaMetrics rounds the specified `start..end` time range to day granularity because of performance optimization concerns. +If you need the exact set of label names and label values on the given time range, then send queries +to [/api/v1/query](https://docs.victoriametrics.com/keyConcepts.html#instant-query) or to [/api/v1/query_range](https://docs.victoriametrics.com/keyConcepts.html#range-query). + +VictoriaMetrics accepts `limit` query arg at [/api/v1/series](https://docs.victoriametrics.com/url-examples.html#apiv1series) +for limiting the number of returned entries. For example, the query to `/api/v1/series?limit=5` returns a sample of up to 5 series, while ignoring the rest of series. +If the provided `limit` value exceeds the corresponding `-search.maxSeries` command-line flag values, then limits specified in the command-line flags are used. Additionally, VictoriaMetrics provides the following handlers: diff --git a/docs/url-examples.md b/docs/url-examples.md index c1f7fcbc5..37f5a4103 100644 --- a/docs/url-examples.md +++ b/docs/url-examples.md @@ -288,7 +288,8 @@ curl http://:8481/select/0/prometheus/api/v1/labels -By default VictoriaMetrics returns labels seen during the last 5 minutes. An arbitrary time range can be set via `start` and `end` query args. +By default VictoriaMetrics returns labels seen during the last day starting at 00:00 UTC. An arbitrary time range can be set via `start` and `end` query args. +The specified `start..end` time range is rounded to day granularity because of performance optimization concerns. Additional information: * [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) @@ -317,7 +318,8 @@ curl http://:8481/select/0/prometheus/api/v1/label/job/values -By default VictoriaMetrics returns label values seen during the last 5 minutes. An arbitrary time range can be set via `start` and `end` query args. +By default VictoriaMetrics returns labels values seen during the last day starting at 00:00 UTC. An arbitrary time range can be set via `start` and `end` query args. +The specified `start..end` time range is rounded to day granularity because of performance optimization concerns. Additional information: * [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) @@ -402,7 +404,8 @@ curl http://:8481/select/0/prometheus/api/v1/series -d 'match[]=vm_htt -By default VictoriaMetrics returns time series seen during the last 5 minutes. An arbitrary time range can be set via `start` and `end` query args. +By default VictoriaMetrics returns time series seen during the last day starting at 00:00 UTC. An arbitrary time range can be set via `start` and `end` query args. +The specified `start..end` time range is rounded to day granularity because of performance optimization concerns. Additional information: * [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) diff --git a/docs/vmagent.md b/docs/vmagent.md index d9789fe7b..5f425b3fa 100644 --- a/docs/vmagent.md +++ b/docs/vmagent.md @@ -1523,7 +1523,7 @@ See the docs at https://docs.victoriametrics.com/vmagent.html . -remoteWrite.relabelConfig string Optional path to file with relabeling configs, which are applied to all the metrics before sending them to -remoteWrite.url. See also -remoteWrite.urlRelabelConfig. The path can point either to local file or to http url. See https://docs.victoriametrics.com/vmagent.html#relabeling -remoteWrite.keepDanglingQueues - Keep persistent queues contents in case there are no matching -remoteWrite.url. Useful when -remoteWrite.url is changed temporarily and persistent queue files will be needed later on. + Keep persistent queues contents at -remoteWrite.tmpDataPath in case there are no matching -remoteWrite.url. Useful when -remoteWrite.url is changed temporarily and persistent queue files will be needed later on. -remoteWrite.roundDigits array Round metric values to this number of decimal digits after the point before writing them to remote storage. Examples: -remoteWrite.roundDigits=2 would round 1.236 to 1.24, while -remoteWrite.roundDigits=-1 would round 126.78 to 130. By default digits rounding is disabled. Set it to 100 for disabling it for a particular remote storage. This option may be used for improving data compression for the stored metrics Supports array of values separated by comma or specified via multiple flags.