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

43
docs/keyConcepts.md
View file

@ -509,10 +509,10 @@ Params:
* `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).
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)
for searching for raw samples in the past when executing the `query`.
For example, request `/api/v1/query?query=up&step=1m` will look for the last written raw sample for metric `up`
on interval between `now()` and `now()-1m`. If omitted, `step` is set to `5m` (5 minutes).
* `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` (used when a sample is missing at the specified instant).
For example, the request `/api/v1/query?query=up&step=1m` will look for the last written raw sample for the metric `up`
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:
@ -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
```
The data sample contains a list of samples for `foo_bar` time series with time intervals between samples from 1m to 3m. If we
plot this data sample on the graph, it will have the following form:
The data above contains a list of samples for the `foo_bar` time series with time intervals between samples
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">
<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>
</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**:
```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
`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,
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
requested timestamp - VictoriaMetrics will try to locate the closest sample on the left to the requested timestamp:
`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`. When there is no raw sample at the
requested timestamp, VictoriaMetrics will try to locate the closest sample before the requested timestamp:
<p style="text-align: center">
<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>
The time range at which VictoriaMetrics will try to locate a missing data sample is equal to `5m`
by default and can be overridden via `step` parameter.
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 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:
* 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;
* 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)
between data points, which must be returned from the range query.
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`
in VictoriaMetrics we need to issue a range query:
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`,
we need to issue a range query:
```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"
@ -704,7 +705,7 @@ curl "http://<victoria-metrics-addr>/api/v1/query_range?query=foo_bar&step=1m&st
```
In response, VictoriaMetrics returns `17` sample-timestamp pairs for the series `foo_bar` at the given time range
from `2022-05-10 09:59:00` to `2022-05-10 10:17:00`. But, if we take a look at the original data sample again, we'll
from `2022-05-10 09:59:00` to `2022-05-10 10:17:00`. But, if we take a look at the original data sample again, we'll
see that it contains only 13 raw samples. What happens here is that the range query is actually
an [instant query](#instant-query) executed `1 + (start-end)/step` times on the time range from `start` to `end`. If we plot
this request in VictoriaMetrics the graph will be shown as the following:
@ -715,9 +716,9 @@ this request in VictoriaMetrics the graph will be shown as the following:
</a>
</p>
The blue dotted lines on the pic are the moments when the instant query was executed. Since instant query retains the
ability to locate the missing point, the graph contains two types of points: `real` and `ephemeral` data
points. `ephemeral` data point always repeats the left closest raw sample (see red arrow on the pic above).
The blue dotted lines in the figure are the moments when the instant query was executed. Since the instant query retains the
ability to return replacements for missing points, the graph contains two types of data points: `real` and `ephemeral`.
`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):
@ -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
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;
* Observe trends and dynamics of the metric change.