From 0b76d07c21daa71c62788c9d52e8c2a891900655 Mon Sep 17 00:00:00 2001 From: Aliaksandr Valialkin Date: Wed, 29 Jun 2022 11:57:35 +0300 Subject: [PATCH] docs/url-examples.md: fix various documentation issues there --- docs/url-examples.md | 341 ++++++++++++++++++++++++------------------- 1 file changed, 193 insertions(+), 148 deletions(-) diff --git a/docs/url-examples.md b/docs/url-examples.md index 84fde9a78b..12378f9c1b 100644 --- a/docs/url-examples.md +++ b/docs/url-examples.md @@ -8,11 +8,11 @@ sort: 21 **Deletes time series from VictoriaMetrics** -Single: +Single-node VictoriaMetrics:
```console -curl -v 'http://:8428/api/v1/admin/tsdb/delete_series?match[]=vm_http_request_errors_total' +curl -v http://localhost:8428/api/v1/admin/tsdb/delete_series -d 'match[]=vm_http_request_errors_total' ```
@@ -39,11 +39,11 @@ The expected output should return [HTTP Status 204](https://datatracker.ietf.org -Cluster: +Cluster version of VictoriaMetrics:
```console -curl -v'http://:8481/delete/0/prometheus/api/v1/admin/tsdb/delete_series?match[]=vm_http_request_errors_total' +curl -v http://:8481/delete/0/prometheus/api/v1/admin/tsdb/delete_series -d 'match[]=vm_http_request_errors_total' ```
@@ -73,113 +73,137 @@ The expected output should return [HTTP Status 204](https://datatracker.ietf.org Additional information: * [How to delete time series](https://docs.victoriametrics.com/#how-to-delete-time-series) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) -## /api/v1/export/csv +## /api/v1/export -**Exports CSV data from VictoriaMetrics** +**Exports raw samples from VictoriaMetrics in JSON line format** -Single: +Single-node VictoriaMetrics:
```console -curl 'http://:8428/api/v1/export/csv?format=__name__,__value__,__timestamp__:unix_s&match=vm_http_request_errors_total' > filename.txt +curl http://localhost:8428/api/v1/export -d 'match[]=vm_http_request_errors_total' > filename.json ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/api/v1/export/csv?format=__name__,__value__,__timestamp__:unix_s&match=vm_http_request_errors_total' > filename.txt +curl http://:8481/select/0/prometheus/api/v1/export -d 'match[]=vm_http_request_errors_total' > filename.json ```
Additional information: -* [How to export time series](https://docs.victoriametrics.com/#how-to-export-csv-data) -* [URL Format](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) +* [How to export time series](https://docs.victoriametrics.com/#how-to-export-time-series) +* [How to import time series](https://docs.victoriametrics.com/#how-to-import-time-series-data) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) -## /api/v1/export/native - -**Exports data from VictoriaMetrics in native format** +## /api/v1/export/csv -Single: +**Exports raw samples from VictoriaMetrics in CSV format** + +Single-node VictoriaMetrics:
```console -curl -G 'http://:8428/api/v1/export/native?match[]=vm_http_request_errors_total' > filename.txt +curl http://localhost:8428/api/v1/export/csv -d 'format=__name__,__value__,__timestamp__:unix_s' -d 'match[]=vm_http_request_errors_total' > filename.csv ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/api/v1/export/native?match=vm_http_request_errors_total' > filename.txt +curl http://:8481/select/0/prometheus/api/v1/export/csv -d 'format=__name__,__value__,__timestamp__:unix_s' -d 'match[]=vm_http_request_errors_total' > filename.csv +``` + +
+ +Additional information: + +* [How to export time series](https://docs.victoriametrics.com/#how-to-export-time-series) +* [How to import time series](https://docs.victoriametrics.com/#how-to-import-time-series-data) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) + +## /api/v1/export/native + +**Exports raw samples from VictoriaMetrics in native format** + +Single-node VictoriaMetrics: +
+ +```console +curl http://localhost:8428/api/v1/export/native -d 'match[]=vm_http_request_errors_total' > filename.bin +``` + +
+ +Cluster version of VictoriaMetrics: +
+ +```console +curl http://:8481/select/0/prometheus/api/v1/export/native -d 'match[]=vm_http_request_errors_total' > filename.bin ```
More information: -* [How to export data in native format](https://docs.victoriametrics.com/#how-to-export-data-in-native-format) +* [How to export time series](https://docs.victoriametrics.com/#how-to-export-time-series) +* [How to import time series](https://docs.victoriametrics.com/#how-to-import-time-series-data) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /api/v1/import -**Imports custom data as well as data obtained via /api/v1/export** +**Imports data to VictoriaMetrics in JSON line format** -Single: +Single-node VictoriaMetrics:
```console -curl --data-binary "@import.txt" -X POST 'http://destination-victoriametrics:8428/api/v1/import' +curl --data-binary "@filename.json" -X POST http://localhost:8428/api/v1/import ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl --data-binary "@import.txt" -X POST 'http://:8480/insert/0/prometheus/api/v1/import' +curl --data-binary "@filename.json" -X POST http://:8480/insert/0/prometheus/api/v1/import ```
-
+More information: -```console -curl -d 'metric_name{foo="bar"} 123' -X POST 'http://:8480/insert/0/prometheus/api/v1/import/prometheus' -``` - -
- -Additional information: - -* [How to import time series data](https://docs.victoriametrics.com/#how-to-import-time-series-data) +* [How to import time series](https://docs.victoriametrics.com/#how-to-import-time-series-data) +* [How to export time series](https://docs.victoriametrics.com/#how-to-export-time-series) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /api/v1/import/csv **Imports CSV data to VictoriaMetrics** -Single: +Single-node VictoriaMetrics:
```console -curl --data-binary "@import.txt" -X POST 'http://localhost:8428/api/v1/import/prometheus' curl -d "GOOG,1.23,4.56,NYSE" 'http://localhost:8428/api/v1/import/csv?format=2:metric:ask,3:metric:bid,1:label:ticker,4:label:market' ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl --data-binary "@import.txt" -X POST 'http://:8480/insert/0/prometheus/api/v1/import/csv' curl -d "GOOG,1.23,4.56,NYSE" 'http://:8480/insert/0/prometheus/api/v1/import/csv?format=2:metric:ask,3:metric:bid,1:label:ticker,4:label:market' ``` @@ -187,210 +211,229 @@ curl -d "GOOG,1.23,4.56,NYSE" 'http://:8480/insert/0/prometheus/api/v1 Additional information: -* [URL format](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) -* [How to import CSV data](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#how-to-import-csv-data) +* [How to import time series](https://docs.victoriametrics.com/#how-to-import-time-series-data) +* [How to export time series](https://docs.victoriametrics.com/#how-to-export-time-series) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) + +## /api/v1/import/native + +**Imports data to VictoriaMetrics in native format** + +Single-node VictoriaMetrics: +
+ +```console +curl -X POST http://localhost:8428/api/v1/import/native -T filename.bin +``` + +Cluster version of VictoriaMetrics: +
+ +```console +curl -X POST http://:8480/insert/0/prometheus/api/v1/import/native -T filename.bin +``` +
+ +Additional information: + +* [How to import time series](https://docs.victoriametrics.com/#how-to-import-time-series-data) +* [How to export time series](https://docs.victoriametrics.com/#how-to-export-time-series) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) + +## /api/v1/import/prometheus + +**Imports data to VictoriaMetrics in Prometheus text exposition format** + +Single-node VictoriaMetrics: +
+ +```console +curl -d 'metric_name{foo="bar"} 123' -X POST http://localhost:8428/api/v1/import/prometheus +``` + +Cluster version of VictoriaMetrics: +
+ +```console +curl -d 'metric_name{foo="bar"} 123' -X POST http://:8480/insert/0/prometheus/api/v1/import/prometheus +``` +
+ +Additional information: + +* [How to import time series](https://docs.victoriametrics.com/#how-to-import-time-series-data) +* [How to export time series](https://docs.victoriametrics.com/#how-to-export-time-series) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /api/v1/labels **Get a list of label names** -Single: +Single-node VictoriaMetrics:
```console -curl -G 'http://localhost:8428/prometheus/api/v1/labels' +curl http://localhost:8428/prometheus/api/v1/labels ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/api/v1/labels' +curl http://:8481/select/0/prometheus/api/v1/labels ```
-Additional information: +Additional information: * [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) * [Querying label values](https://prometheus.io/docs/prometheus/latest/querying/api/#querying-label-values) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) -## /api/v1/label/\/values +## /api/v1/label/.../values -**Querying label values** +**Get a list of values for a particular label** -Single: +Single-node VictoriaMetrics:
```console -curl -G 'http://localhost:8428/prometheus/api/v1/label/job/values' +curl http://localhost:8428/prometheus/api/v1/label/job/values ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/api/v1/label/job/values' +curl http://:8481/select/0/prometheus/api/v1/label/job/values ```
-Additional information: +Additional information: +* [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) * [Getting label names](https://prometheus.io/docs/prometheus/latest/querying/api/#getting-label-names) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /api/v1/query **Performs PromQL/MetricsQL instant query** -Single: +Single-node VictoriaMetrics:
```console -curl -G 'http://localhost:8428/prometheus/api/v1/query?query=vm_http_request_errors_total&time=2021-02-22T19:10:30.781Z' +curl http://localhost:8428/prometheus/api/v1/query -d 'query=vm_http_request_errors_total' ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/api/v1/query?query=vm_http_request_errors_total&time=2021-02-22T19:10:30.781Z' +curl http://:8481/select/0/prometheus/api/v1/query -d 'query=vm_http_request_errors_total' ```
-Additional information: +Additional information: * [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) * [Instant queries](https://docs.victoriametrics.com/keyConcepts.html#instant-query) * [Query language](https://docs.victoriametrics.com/keyConcepts.html#metricsql) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /api/v1/query_range -**Performs PromQL/MetricsQL range_query** +**Performs PromQL/MetricsQL range query** -Single: +Single-node VictoriaMetrics:
```console -curl -G 'http://localhost:8428/prometheus/api/v1/query_range?query=vm_http_request_errors_total&start=2021-02-22T19:10:30.781Z&step=20m' +curl http://localhost:8428/prometheus/api/v1/query_range -d 'query=sum(increase(vm_http_request_errors_total{job="foo"}[5m]))' -d 'start=-1d' -d 'step=1h' ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/api/v1/query_range?query=vm_http_request_errors_total&start=2021-02-22T19:10:30.781Z&step=20m' +curl http://:8481/select/0/prometheus/api/v1/query_range -d 'query=sum(increase(vm_http_request_errors_total{job="foo"}[5m]))' -d 'start=-1d' -d 'step=1h' ```
-
- -```console -curl -G 'http://:8481/select/0/prometheus/api/v1/query_range?query=vm_http_request_errors_total&start=-1h&step=10m' -``` - -```console -curl -G http://:8481/select/0/prometheus/api/v1/query_range --data-urlencode 'query=sum(increase(vm_http_request_errors_total{status=""}[5m])) by (status)' -``` - -
- -Additional information: +Additional information: * [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) * [Range queries](https://docs.victoriametrics.com/keyConcepts.html#range-query) * [Query language](https://docs.victoriametrics.com/keyConcepts.html#metricsql) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /api/v1/series -**Finding series by label matchers** +**Returns series names with their labels** -Single: +Single-node VictoriaMetrics:
```console -curl -G 'http://localhost:8428/prometheus/api/v1/series?match[]=vm_http_request_errors_total&start=-1h' +curl http://localhost:8428/prometheus/api/v1/series -d 'match[]=vm_http_request_errors_total' ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/api/v1/series?match[]=vm_http_request_errors_total&start=-1h' +curl http://:8481/select/0/prometheus/api/v1/series -d 'match[]=vm_http_request_errors_total' ```
-Additional information: +Additional information: * [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) * [Finding series by label matchers](https://prometheus.io/docs/prometheus/latest/querying/api/#finding-series-by-label-matchers) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /api/v1/status/tsdb **Cardinality statistics** -Single: +Single-node VictoriaMetrics:
```console -curl -G 'http://localhost:8428/prometheus/api/v1/status/tsdb' +curl http://localhost:8428/prometheus/api/v1/status/tsdb ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/api/v1/status/tsdb' +curl http://:8481/select/0/prometheus/api/v1/status/tsdb ```
-Additional information: +Additional information: * [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) * [TSDB Stats](https://prometheus.io/docs/prometheus/latest/querying/api/#tsdb-stats) - -## /api/v1/targets - -**Checking targets** - -Should be sent to vmagent/VMsingle - -Single: -
- -```console -curl -G 'http://:8428/api/v1/targets' -``` - -
- -
- -```console -curl -G 'http://:8429/api/v1/targets' -``` - -
- -Additional information: -* [Prometheus querying API usage](https://docs.victoriametrics.com/#prometheus-querying-api-usage) -* [Targets](https://prometheus.io/docs/prometheus/latest/querying/api/#targets) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /datadog/api/v1/series -**Sends data from DataDog agent to VM** +**Imports data in DataDog format into VictoriaMetrics** -Single: +Single-node VictoriaMetrics:
```console @@ -417,7 +460,7 @@ echo '
-Cluster: +Cluster version of VictoriaMetrics:
```console @@ -447,25 +490,26 @@ echo ' Additional information: * [How to send data from datadog agent](https://docs.victoriametrics.com/#how-to-send-data-from-datadog-agent) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /federate **Returns federated metrics** -Single: +Single-node VictoriaMetrics:
```console -curl -G 'http://localhost:8428/federate?match[]=vm_http_request_errors_total&start=2021-02-22T19:10:30.781Z' +curl http://localhost:8428/federate -d 'match[]=vm_http_request_errors_total' ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/prometheus/federate?match[]=vm_http_request_errors_total&start=2021-02-22T19:10:30.781Z' +curl http://:8481/select/0/prometheus/federate -d 'match[]=vm_http_request_errors_total' ```
@@ -474,60 +518,63 @@ Additional information: * [Federation](https://docs.victoriametrics.com/#federation) * [Prometheus-compatible federation data](https://prometheus.io/docs/prometheus/latest/federation/#configuring-federation) +* [URL format for VictoriaMetrics cluster](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /graphite/metrics/find **Searches Graphite metrics in VictoriaMetrics** -Single: +Single-node VictoriaMetrics:
```console -curl -G 'http://localhost:8428/graphite/metrics/find?query=vm_http_request_errors_total' +curl http://localhost:8428/graphite/metrics/find -d 'query=vm_http_request_errors_total' ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -G 'http://:8481/select/0/graphite/metrics/find?query=vm_http_request_errors_total' +curl http://:8481/select/0/graphite/metrics/find -d 'query=vm_http_request_errors_total' ```
Additional information: -* [Metrics find](https://graphite-api.readthedocs.io/en/latest/api.html#metrics-find) -* [How to send data from graphite compatible agents such as statsd](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#how-to-send-data-from-graphite-compatible-agents-such-as-statsd) +* [Metrics find API in Graphite](https://graphite-api.readthedocs.io/en/latest/api.html#metrics-find) +* [Graphite API in VictoriaMetrics](https://docs.victoriametrics.com/#graphite-api-usage) +* [How to send Graphite data to VictoriaMetrics](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#how-to-send-data-from-graphite-compatible-agents-such-as-statsd) * [URL Format](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## /influx/write **Writes data with InfluxDB line protocol to VictoriaMetrics** -Single: +Single-node VictoriaMetrics:
```console -curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST 'http://localhost:8428/write' +curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST http://localhost:8428/write ```
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST 'http://:8480/insert/0/influx/write' +curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST http://:8480/insert/0/influx/write ```
Additional information: -* [How to send data from influxdb compatible agents such as telegraf](https://docs.victoriametrics.com/#how-to-send-data-from-influxdb-compatible-agents-such-as-telegraf) +* [How to send Influx data to VictoriaMetrics](https://docs.victoriametrics.com/#how-to-send-data-from-influxdb-compatible-agents-such-as-telegraf) +* [URL Format](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#url-format) ## TCP and UDP @@ -536,7 +583,7 @@ Additional information: Turned off by default. Enable OpenTSDB receiver in VictoriaMetrics by setting `-opentsdbListenAddr` command-line flag. *If run from docker, '-opentsdbListenAddr' port should be exposed* -Single: +Single-node VictoriaMetrics:
```console @@ -545,7 +592,7 @@ echo "put foo.bar.baz `date +%s` 123 tag1=value1 tag2=value2" | nc -N localhost
-Cluster: +Cluster version of VictoriaMetrics:
```console @@ -556,7 +603,7 @@ echo "put foo.bar.baz `date +%s` 123 tag1=value1 tag2=value2 VictoriaMetrics_Ac Enable HTTP server for OpenTSDB /api/put requests by setting `-opentsdbHTTPListenAddr` command-line flag. -Single: +Single-node VictoriaMetrics:
```console @@ -565,36 +612,34 @@ curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"m
-Cluster: +Cluster version of VictoriaMetrics:
```console -curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]' - 'http://:8480/insert/42/opentsdb/api/put' +curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]' http://:8480/insert/42/opentsdb/api/put ```
Additional information: -* [Api http put](http://opentsdb.net/docs/build/html/api_http/put.html) -* [How to send data from opentsdb compatible agents](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#how-to-send-data-from-opentsdb-compatible-agents) +* [OpenTSDB http put API](http://opentsdb.net/docs/build/html/api_http/put.html) +* [How to send data OpenTSDB data to VictoriaMetrics](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#how-to-send-data-from-opentsdb-compatible-agents) -**How to write data with Graphite plaintext protocol to VictoriaMetrics** +**How to send Graphite data to VictoriaMetrics** Enable Graphite receiver in VictoriaMetrics by setting `-graphiteListenAddr` command-line flag. -Single: +Single-node VictoriaMetrics:
```console -echo "foo.bar.baz;tag1=value1;tag2=value2 123 `date +%s`" | - nc -N localhost 2003 +echo "foo.bar.baz;tag1=value1;tag2=value2 123 `date +%s`" | nc -N localhost 2003 ```
-Cluster: +Cluster version of VictoriaMetrics:
```console @@ -605,7 +650,7 @@ echo "foo.bar.baz;tag1=value1;tag2=value2;VictoriaMetrics_AccountID=42 123 `date Additional information: -`VictoriaMetrics_AccountID=42` - tag that indicated tenant ID. +`VictoriaMetrics_AccountID=42` - [tenant ID](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#multitenancy) in cluster version of VictoriaMetrics -* [Request handler](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/a3eafd2e7fc75776dfc19d3c68c85589454d9dce/app/vminsert/opentsdb/request_handler.go#L47) -* [How to send data from graphite compatible agents such as statsd](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#how-to-send-data-from-graphite-compatible-agents-such-as-statsd) +* [How to send Graphite data to VictoriaMetrics](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#how-to-send-data-from-graphite-compatible-agents-such-as-statsd) +* [Multitenancy in cluster version of VictoriaMetrics](https://docs.victoriametrics.com/Cluster-VictoriaMetrics.html#multitenancy)