From b79d4cc988d61d3a26d153cd1f6e60afc6014568 Mon Sep 17 00:00:00 2001 From: Dan Dascalescu Date: Tue, 9 Jan 2024 05:29:21 -0500 Subject: [PATCH] docs: fix English in keyConcepts.md, add instant query use case (#5547) --- docs/keyConcepts.md | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/keyConcepts.md b/docs/keyConcepts.md index 94bb2edbc..91cf7715a 100644 --- a/docs/keyConcepts.md +++ b/docs/keyConcepts.md @@ -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:

@@ -541,7 +541,7 @@ plot this data sample on the graph, it will have the following form:

-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:///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:

@@ -580,13 +580,14 @@ requested timestamp - VictoriaMetrics will try to locate the closest sample on t

-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:///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:///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:

-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.