mirror of
https://github.com/VictoriaMetrics/VictoriaMetrics.git
synced 2024-11-21 14:44:00 +00:00
docs: fix English in keyConcepts.md, add instant query use case (#5547)
This commit is contained in:
Dan Dascalescu
GitHub
parent
e34f77aed4
commit
b79d4cc988
1 changed files with 22 additions and 21 deletions
|
|
@ -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"
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue