github-mirrors/VictoriaMetrics
1
0
Fork 0
mirror of https://github.com/VictoriaMetrics/VictoriaMetrics.git synced 2024-11-21 14:44:00 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: fix English in keyConcepts.md, add instant query use case (#5547)

Browse source
This commit is contained in:
Dan Dascalescu 2024-01-09 05:29:21 -05:00 committed by GitHub
parent e34f77aed4
commit b79d4cc988
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 22 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
docs/keyConcepts.md
View file

@ -509,10 +509,10 @@ Params:
* `time` - optional, [timestamp](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#timestamp-formats) * `time` - optional, [timestamp](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#timestamp-formats)
in second precision to evaluate the `query` at. If omitted, `time` is set to `now()` (current timestamp). in second precision to evaluate the `query` at. If omitted, `time` is set to `now()` (current timestamp).
The `time` param can be specified in [multiple allowed formats](https://docs.victoriametrics.com/#timestamp-formats). The `time` param can be specified in [multiple allowed formats](https://docs.victoriametrics.com/#timestamp-formats).
* `step` - optional, the max [interval](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations) * `step` - optional, the maximum [interval](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations)
for searching for raw samples in the past when executing the `query`. for searching for raw samples in the past when executing the `query` (used when a sample is missing at the specified instant).
For example, request `/api/v1/query?query=up&step=1m` will look for the last written raw sample for metric `up` For example, the request `/api/v1/query?query=up&step=1m` will look for the last written raw sample for the metric `up`
on interval between `now()` and `now()-1m`. If omitted, `step` is set to `5m` (5 minutes). in the interval between `now()` and `now()-1m`. If omitted, `step` is set to `5m` (5 minutes).
To understand how instant queries work, let's begin with a data sample: To understand how instant queries work, let's begin with a data sample:
@ -532,8 +532,8 @@ foo_bar 1.00 1652170500000 # 2022-05-10 10:15:00
foo_bar 4.00 1652170560000 # 2022-05-10 10:16:00 foo_bar 4.00 1652170560000 # 2022-05-10 10:16:00
``` ```
The data sample contains a list of samples for `foo_bar` time series with time intervals between samples from 1m to 3m. If we The data above contains a list of samples for the `foo_bar` time series with time intervals between samples
plot this data sample on the graph, it will have the following form: ranging from 1m to 3m. If we plot this data sample on the graph, it will have the following form:
<p style="text-align: center"> <p style="text-align: center">
<a href="keyConcepts_data_samples.webp" target="_blank"> <a href="keyConcepts_data_samples.webp" target="_blank">
@ -541,7 +541,7 @@ plot this data sample on the graph, it will have the following form:
</a> </a>
</p> </p>
To get the value of `foo_bar` metric at some specific moment of time, for example `2022-05-10 10:03:00`, in To get the value of the `foo_bar` series at some specific moment of time, for example `2022-05-10 10:03:00`, in
VictoriaMetrics we need to issue an **instant query**: VictoriaMetrics we need to issue an **instant query**:
```console ```console
@ -569,9 +569,9 @@ curl "http://<victoria-metrics-addr>/api/v1/query?query=foo_bar&time=2022-05-10T
``` ```
In response, VictoriaMetrics returns a single sample-timestamp pair with a value of `3` for the series In response, VictoriaMetrics returns a single sample-timestamp pair with a value of `3` for the series
`foo_bar` at the given moment of time `2022-05-10 10:03`. But, if we take a look at the original data sample again, `foo_bar` at the given moment in time `2022-05-10 10:03`. But, if we take a look at the original data sample again,
we'll see that there is no raw sample at `2022-05-10 10:03`. What happens here if there is no raw sample at the we'll see that there is no raw sample at `2022-05-10 10:03`. When there is no raw sample at the
requested timestamp - VictoriaMetrics will try to locate the closest sample on the left to the requested timestamp: requested timestamp, VictoriaMetrics will try to locate the closest sample before the requested timestamp:
<p style="text-align: center"> <p style="text-align: center">
<a href="keyConcepts_instant_query.webp" target="_blank"> <a href="keyConcepts_instant_query.webp" target="_blank">
@ -580,13 +580,14 @@ requested timestamp - VictoriaMetrics will try to locate the closest sample on t
</p> </p>
The time range at which VictoriaMetrics will try to locate a missing data sample is equal to `5m` The time range in which VictoriaMetrics will try to locate a replacement for a missing data sample is equal to `5m`
by default and can be overridden via `step` parameter. by default and can be overridden via the `step` parameter.
Instant query can return multiple time series, but always only one data sample per series. Instant queries are used in Instant queries can return multiple time series, but always only one data sample per series. Instant queries are used in
the following scenarios: the following scenarios:
* Getting the last recorded value; * Getting the last recorded value;
* For [rollup functions](https://docs.victoriametrics.com/MetricsQL.html#rollup-functions) such as `count_over_time`;
* For alerts and recording rules evaluation; * For alerts and recording rules evaluation;
* Plotting Stat or Table panels in Grafana. * Plotting Stat or Table panels in Grafana.
@ -608,10 +609,10 @@ Params:
* `step` - the [interval](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations) * `step` - the [interval](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations)
between data points, which must be returned from the range query. between data points, which must be returned from the range query.
The `query` is executed at `start`, `start+step`, `start+2*step`, ..., `end` timestamps. The `query` is executed at `start`, `start+step`, `start+2*step`, ..., `end` timestamps.
If the `step` isn't set, then it is automatically set to `5m` (5 minutes). If the `step` isn't set, then it default to `5m` (5 minutes).
To get the values of `foo_bar` on the time range from `2022-05-10 09:59:00` to `2022-05-10 10:17:00` For example, to get the values of `foo_bar` during the time range from `2022-05-10 09:59:00` to `2022-05-10 10:17:00`,
in VictoriaMetrics we need to issue a range query: we need to issue a range query:
```console ```console
curl "http://<victoria-metrics-addr>/api/v1/query_range?query=foo_bar&step=1m&start=2022-05-10T09:59:00.000Z&end=2022-05-10T10:17:00.000Z" curl "http://<victoria-metrics-addr>/api/v1/query_range?query=foo_bar&step=1m&start=2022-05-10T09:59:00.000Z&end=2022-05-10T10:17:00.000Z"
@ -715,9 +716,9 @@ this request in VictoriaMetrics the graph will be shown as the following:
</a> </a>
</p> </p>
The blue dotted lines on the pic are the moments when the instant query was executed. Since instant query retains the The blue dotted lines in the figure are the moments when the instant query was executed. Since the instant query retains the
ability to locate the missing point, the graph contains two types of points: `real` and `ephemeral` data ability to return replacements for missing points, the graph contains two types of data points: `real` and `ephemeral`.
points. `ephemeral` data point always repeats the left closest raw sample (see red arrow on the pic above). `ephemeral` data points always repeat the closest raw sample that occurred before (see red arrow on the pic above).
This behavior of adding ephemeral data points comes from the specifics of the [pull model](#pull-model): This behavior of adding ephemeral data points comes from the specifics of the [pull model](#pull-model):
@ -738,7 +739,7 @@ window to fill gaps and detect stale series at the same time.
Range queries are mostly used for plotting time series data over specified time ranges. These queries are extremely Range queries are mostly used for plotting time series data over specified time ranges. These queries are extremely
useful in the following scenarios: useful in the following scenarios:
* Track the state of a metric on the time interval; * Track the state of a metric on the given time interval;
* Correlate changes between multiple metrics on the time interval; * Correlate changes between multiple metrics on the time interval;
* Observe trends and dynamics of the metric change. * Observe trends and dynamics of the metric change.