Skip to content

Commit 52db36a

Browse files
committed
docs/victorialogs/querying/README.md: group the description for the time-based query args at /select/logsql/stats_query and /select/logsql/stats_query_range docs
Previously the description for `time`, `start`, `end` and `step` query args was split into two parts with the description for the `query` query arg in the middle. This complicated reading the docs.
1 parent 568a969 commit 52db36a

File tree

1 file changed

+16
-14
lines changed

1 file changed

+16
-14
lines changed

docs/victorialogs/querying/README.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -452,6 +452,9 @@ VictoriaLogs provides `/select/logsql/stats_query?query=<query>&time=<t>` HTTP e
452452
for the given [`query`](https://docs.victoriametrics.com/victorialogs/logsql/) at the given timestamp `t`
453453
in the format compatible with [Prometheus querying API](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries).
454454

455+
The `<t>` arg can contain values in [any supported format](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#timestamp-formats).
456+
If `<t>` is missing, then it equals to the current time.
457+
455458
The `<query>` must contain [`stats` pipe](https://docs.victoriametrics.com/victorialogs/logsql/#stats-pipe). The calculated stats is converted into metrics
456459
with labels from `by(...)` clause of the `| stats by(...)` pipe.
457460

@@ -461,9 +464,6 @@ and [`row_max`](https://docs.victoriametrics.com/victorialogs/logsql/#row_max-st
461464
Additional labels can be created from metrics via [`format` pipe](https://docs.victoriametrics.com/victorialogs/logsql/#format-pipe).
462465
Additional metrics can be created from the existing metrics via [`math` pipe](https://docs.victoriametrics.com/victorialogs/logsql/#math-pipe).
463466

464-
The `<t>` arg can contain values in [any supported format](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#timestamp-formats).
465-
If `<t>` is missing, then it equals to the current time.
466-
467467
For example, the following command returns the number of logs per each `level` [field](https://docs.victoriametrics.com/victorialogs/keyconcepts/#data-model)
468468
across logs over `2024-01-01` day by UTC:
469469

@@ -515,6 +515,7 @@ Below is an example JSON output returned from this endpoint:
515515
```
516516

517517
The `/select/logsql/stats_query` API is useful for generating Prometheus-compatible alerts and calculating recording rules results.
518+
It is used by [vmalert](https://docs.victoriametrics.com/victorialogs/vmalert/).
518519

519520
The `/select/logsql/stats_query` returns the following additional HTTP response headers:
520521

@@ -535,6 +536,17 @@ VictoriaLogs provides `/select/logsql/stats_query_range?query=<query>&start=<sta
535536
for the given [`query`](https://docs.victoriametrics.com/victorialogs/logsql/) on the given `[start ... end)` time range with the given `step` interval.
536537
The stats is returned in the format compatible with [Prometheus querying API](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries).
537538

539+
The `<start>` and `<end>` args can contain values in [any supported format](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#timestamp-formats).
540+
If `<start>` is missing, then it equals to the minimum timestamp across logs stored in VictoriaLogs.
541+
If `<end>` is missing, then it equals to the maximum timestamp across logs stored in VictoriaLogs.
542+
543+
The `<step>` arg can contain values in [the format specified here](https://docs.victoriametrics.com/victorialogs/logsql/#stats-by-time-buckets).
544+
If `<step>` is missing, then it equals to `1d` (one day).
545+
546+
Note: The `/select/logsql/stats_query_range` endpoint
547+
relies on `_time` field for time bucketing and therefore does not allow any pipe to change or remove the `_time` before the `| stats ...` pipe.
548+
In contrast, queries passed to [`/select/logsql/stats_query`](https://docs.victoriametrics.com/victorialogs/querying/#querying-log-stats) can include any pipes before the `| stats ...` pipe, including pipes that modify or remove the `_time` field.
549+
538550
The `<query>` must contain [`stats` pipe](https://docs.victoriametrics.com/victorialogs/logsql/#stats-pipe). The calculated stats is converted into metrics
539551
with labels from `by(...)` clause of the `| stats by(...)` pipe.
540552

@@ -548,17 +560,6 @@ It may be useful to use [`running_stats`](https://docs.victoriametrics.com/victo
548560
and [`total_stats`](https://docs.victoriametrics.com/victorialogs/logsql/#total_stats-pipe) pipes for calculating running and total stats over the stats
549561
returned by the [`stats` pipe](https://docs.victoriametrics.com/victorialogs/logsql/#stats-pipe).
550562

551-
The `<start>` and `<end>` args can contain values in [any supported format](https://docs.victoriametrics.com/victoriametrics/single-server-victoriametrics/#timestamp-formats).
552-
If `<start>` is missing, then it equals to the minimum timestamp across logs stored in VictoriaLogs.
553-
If `<end>` is missing, then it equals to the maximum timestamp across logs stored in VictoriaLogs.
554-
555-
The `<step>` arg can contain values in [the format specified here](https://docs.victoriametrics.com/victorialogs/logsql/#stats-by-time-buckets).
556-
If `<step>` is missing, then it equals to `1d` (one day).
557-
558-
Note: The `/select/logsql/stats_query_range` endpoint
559-
relies on `_time` field for time bucketing and therefore does not allow any pipe to change or remove the `_time` before the `| stats ...` pipe.
560-
In contrast, queries passed to [`/select/logsql/stats_query`](https://docs.victoriametrics.com/victorialogs/querying/#querying-log-stats) can include any pipes before the `| stats ...` pipe, including pipes that modify or remove the `_time` field.
561-
562563
For example, the following command returns the number of logs per each `level` [field](https://docs.victoriametrics.com/victorialogs/keyconcepts/#data-model)
563564
across logs over `2024-01-01` day by UTC with 6-hour granularity:
564565

@@ -628,6 +629,7 @@ Below is an example JSON output returned from this endpoint:
628629
```
629630

630631
The `/select/logsql/stats_query_range` API is useful for generating Prometheus-compatible graphs in Grafana.
632+
It is used by [Grafana plugin for VictoriaLogs](https://docs.victoriametrics.com/victorialogs/integrations/grafana/).
631633

632634
The `/select/logsql/stats_query_range` returns the following additional HTTP response headers:
633635

0 commit comments

Comments
 (0)