77c3bbf3fc
### Describe Your Changes
* `sort` param is unused by the current website engine, and was present only for compatibility
with previous website engine. It is time to remove it as it makes no effect
* re-structure guides content into folders to simplify assets management
### Checklist
The following checks are **mandatory**:
- [ ] My change adheres [VictoriaMetrics contributing
guidelines](https://docs.victoriametrics.com/contributing/).
(cherry picked from commit 35d77a3bed)
20 KiB
| weight | title | menu | aliases | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 33 | API examples |
|
|
/api/v1/admin/tsdb/delete_series
Deletes time series from VictoriaMetrics
Note that handler accepts any HTTP method, so sending a GET request to /api/v1/admin/tsdb/delete_series will result in deletion of time series.
Single-node VictoriaMetrics:
curl -v http://localhost:8428/api/v1/admin/tsdb/delete_series -d 'match[]=vm_http_request_errors_total'
The expected output should return HTTP Status 204 and will look like:
* Trying 127.0.0.1:8428...
* Connected to 127.0.0.1 (127.0.0.1) port 8428 (#0)
> GET /api/v1/admin/tsdb/delete_series?match[]=vm_http_request_errors_total HTTP/1.1
> Host: 127.0.0.1:8428
> User-Agent: curl/7.81.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 204 No Content
< X-Server-Hostname: eba075fb0e1a
< Date: Tue, 21 Jun 2022 07:33:35 GMT
<
* Connection #0 to host 127.0.0.1 left intact
Cluster version of VictoriaMetrics:
curl -v http://<vmselect>:8481/delete/0/prometheus/api/v1/admin/tsdb/delete_series -d 'match[]=vm_http_request_errors_total'
The expected output should return HTTP Status 204 and will look like:
* Trying 127.0.0.1:8481...
* Connected to 127.0.0.1 (127.0.0.1) port 8481 (#0)
> GET /delete/0/prometheus/api/v1/admin/tsdb/delete_series?match[]=vm_http_request_errors_total HTTP/1.1
> Host: 127.0.0.1:8481
> User-Agent: curl/7.81.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 204 No Content
< X-Server-Hostname: 101ed7a45c94
< Date: Tue, 21 Jun 2022 07:21:36 GMT
<
* Connection #0 to host 127.0.0.1 left intact
Additional information:
/api/v1/export
Exports raw samples from VictoriaMetrics in JSON line format
Single-node VictoriaMetrics:
curl http://localhost:8428/api/v1/export -d 'match[]=vm_http_request_errors_total' > filename.json
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/prometheus/api/v1/export -d 'match[]=vm_http_request_errors_total' > filename.json
Additional information:
- How to export time series
- How to import time series
- How to export data in JSON line format
- URL format for VictoriaMetrics cluster
/api/v1/export/csv
Exports raw samples from VictoriaMetrics in CSV format
Single-node VictoriaMetrics:
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 version of VictoriaMetrics:
curl http://<vmselect>: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:
/api/v1/export/native
Exports raw samples from VictoriaMetrics in native format
Single-node VictoriaMetrics:
curl http://localhost:8428/api/v1/export/native -d 'match[]=vm_http_request_errors_total' > filename.bin
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/prometheus/api/v1/export/native -d 'match[]=vm_http_request_errors_total' > filename.bin
More information:
/api/v1/import
Imports data to VictoriaMetrics in JSON line format
Single-node VictoriaMetrics:
curl -H 'Content-Type: application/json' --data-binary "@filename.json" -X POST http://localhost:8428/api/v1/import
Cluster version of VictoriaMetrics:
curl -H 'Content-Type: application/json' --data-binary "@filename.json" -X POST http://<vminsert>:8480/insert/0/prometheus/api/v1/import
More information:
/api/v1/import/csv
Imports CSV data to VictoriaMetrics
Single-node VictoriaMetrics:
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 version of VictoriaMetrics:
curl -d "GOOG,1.23,4.56,NYSE" 'http://<vminsert>:8480/insert/0/prometheus/api/v1/import/csv?format=2:metric:ask,3:metric:bid,1:label:ticker,4:label:market'
Additional information:
/api/v1/import/native
Imports data to VictoriaMetrics in native format
Single-node VictoriaMetrics:
curl -X POST http://localhost:8428/api/v1/import/native -T filename.bin
Cluster version of VictoriaMetrics:
curl -X POST http://<vminsert>:8480/insert/0/prometheus/api/v1/import/native -T filename.bin
Additional information:
/api/v1/import/prometheus
Imports data to VictoriaMetrics in Prometheus text exposition format
Single-node VictoriaMetrics:
curl -d 'metric_name{foo="bar"} 123' -X POST http://localhost:8428/api/v1/import/prometheus
Cluster version of VictoriaMetrics:
curl -d 'metric_name{foo="bar"} 123' -X POST http://<vminsert>:8480/insert/0/prometheus/api/v1/import/prometheus
Additional information:
/api/v1/labels
Get a list of label names at the given time range
Single-node VictoriaMetrics:
curl http://localhost:8428/prometheus/api/v1/labels
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/prometheus/api/v1/labels
By default, VictoriaMetrics returns labels seen during the last day starting at 00:00 UTC because of performance reasons.
An arbitrary time range can be set via start and end query args.
The specified start..end time range is rounded to UTC day granularity because of performance reasons.
Additional information:
/api/v1/label/.../values
Get a list of values for a particular label on the given time range
Single-node VictoriaMetrics:
curl http://localhost:8428/prometheus/api/v1/label/job/values
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/prometheus/api/v1/label/job/values
By default, VictoriaMetrics returns labels values seen during the last day starting at 00:00 UTC because of performance reasons.
An arbitrary time range can be set via start and end query args.
The specified start..end time range is rounded to UTC day granularity because of performance reasons.
Additional information:
/api/v1/query
Performs PromQL/MetricsQL instant query
Single-node VictoriaMetrics:
curl http://localhost:8428/prometheus/api/v1/query -d 'query=vm_http_request_errors_total'
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/prometheus/api/v1/query -d 'query=vm_http_request_errors_total'
Additional information:
/api/v1/query_range
Performs PromQL/MetricsQL range query
Single-node VictoriaMetrics:
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 version of VictoriaMetrics:
curl http://<vmselect>: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'
Additional information:
/api/v1/series
Returns series names with their labels on the given time range
Single-node VictoriaMetrics:
curl http://localhost:8428/prometheus/api/v1/series -d 'match[]=vm_http_request_errors_total'
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/prometheus/api/v1/series -d 'match[]=vm_http_request_errors_total'
By default, VictoriaMetrics returns time series seen during the last day starting at 00:00 UTC because of performance reasons.
An arbitrary time range can be set via start and end query args.
The specified start..end time range is rounded to UTC day granularity because of performance reasons.
Additional information:
- Finding series by label matchers
- Prometheus querying API usage
- URL format for VictoriaMetrics cluster
VictoriaMetrics accepts
limitquery arg for/api/v1/serieshandlers for limiting the number of returned entries. For example, the query to/api/v1/series?limit=5returns a sample of up to 5 series, while ignoring the rest. If the providedlimitvalue exceeds the corresponding-search.maxSeriescommand-line flag values, then limits specified in the command-line flags are used.
/api/v1/status/tsdb
Cardinality statistics
Single-node VictoriaMetrics:
curl http://localhost:8428/prometheus/api/v1/status/tsdb
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/prometheus/api/v1/status/tsdb
Additional information:
/datadog
DataDog URL for Single-node VictoriaMetrics
http://victoriametrics:8428/datadog
DataDog URL for Cluster version of VictoriaMetrics
http://vminsert:8480/insert/0/datadog
/datadog/api/v1/series
Imports data in DataDog v1 format into VictoriaMetrics
Single-node VictoriaMetrics:
echo '
{
"series": [
{
"host": "test.example.com",
"interval": 20,
"metric": "system.load.1",
"points": [[
0,
0.5
]],
"tags": [
"environment:test"
],
"type": "rate"
}
]
}
' | curl -X POST -H 'Content-Type: application/json' --data-binary @- http://localhost:8428/datadog/api/v1/series
Cluster version of VictoriaMetrics:
echo '
{
"series": [
{
"host": "test.example.com",
"interval": 20,
"metric": "system.load.1",
"points": [[
0,
0.5
]],
"tags": [
"environment:test"
],
"type": "rate"
}
]
}
' | curl -X POST -H 'Content-Type: application/json' --data-binary @- 'http://<vminsert>:8480/insert/0/datadog/api/v1/series'
Additional information:
/datadog/api/v2/series
Imports data in DataDog v2 format into VictoriaMetrics
Single-node VictoriaMetrics:
echo '
{
"series": [
{
"metric": "system.load.1",
"type": 0,
"points": [
{
"timestamp": 0,
"value": 0.7
}
],
"resources": [
{
"name": "dummyhost",
"type": "host"
}
],
"tags": ["environment:test"]
}
]
}
' | curl -X POST -H 'Content-Type: application/json' --data-binary @- http://localhost:8428/datadog/api/v2/series
Cluster version of VictoriaMetrics:
echo '
{
"series": [
{
"metric": "system.load.1",
"type": 0,
"points": [
{
"timestamp": 0,
"value": 0.7
}
],
"resources": [
{
"name": "dummyhost",
"type": "host"
}
],
"tags": ["environment:test"]
}
]
}
' | curl -X POST -H 'Content-Type: application/json' --data-binary @- 'http://<vminsert>:8480/insert/0/datadog/api/v2/series'
Additional information:
/federate
Returns federated metrics
Single-node VictoriaMetrics:
curl http://localhost:8428/federate -d 'match[]=vm_http_request_errors_total'
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/prometheus/federate -d 'match[]=vm_http_request_errors_total'
Additional information:
/graphite/metrics/find
Searches Graphite metrics in VictoriaMetrics
Single-node VictoriaMetrics:
curl http://localhost:8428/graphite/metrics/find -d 'query=vm_http_request_errors_total'
Cluster version of VictoriaMetrics:
curl http://<vmselect>:8481/select/0/graphite/metrics/find -d 'query=vm_http_request_errors_total'
Additional information:
- Metrics find API in Graphite
- Graphite API in VictoriaMetrics
- How to send Graphite data to VictoriaMetrics
- URL Format
/influx/write
Writes data with InfluxDB line protocol to VictoriaMetrics
Single-node VictoriaMetrics:
curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST http://localhost:8428/write
Cluster version of VictoriaMetrics:
curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST http://<vminsert>:8480/insert/0/influx/write
Additional information:
/internal/resetRollupResultCache
Resets the response cache for previously served queries. It is recommended to invoke after backfilling procedure.
Single-node VictoriaMetrics:
curl -Is http://localhost:8428/internal/resetRollupResultCache
Cluster version of VictoriaMetrics:
curl -Is http://<vmselect>:8481/select/internal/resetRollupResultCache
vmselect will propagate this call to the rest of the vmselects listed in its -selectNode cmd-line flag. If this
flag isn't set, then cache need to be purged from each vmselect individually.
TCP and UDP
How to send data from OpenTSDB-compatible agents to VictoriaMetrics
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-node VictoriaMetrics:
echo "put foo.bar.baz `date +%s` 123 tag1=value1 tag2=value2" | nc -N localhost 4242
Cluster version of VictoriaMetrics:
echo "put foo.bar.baz `date +%s` 123 tag1=value1 tag2=value2" | nc -N http://<vminsert> 4242
Enable HTTP server for OpenTSDB /api/put requests by setting -opentsdbHTTPListenAddr command-line flag.
Single-node VictoriaMetrics:
curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]' http://localhost:4242/api/put
Cluster version of VictoriaMetrics:
curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]' http://<vminsert>:8480/insert/42/opentsdb/api/put
Additional information:
How to send Graphite data to VictoriaMetrics
Enable Graphite receiver in VictoriaMetrics by setting -graphiteListenAddr command-line flag.
Single-node VictoriaMetrics:
echo "foo.bar.baz;tag1=value1;tag2=value2 123 `date +%s`" | nc -N localhost 2003
Cluster version of VictoriaMetrics:
echo "foo.bar.baz;tag1=value1;tag2=value2 123 `date +%s`" | nc -N http://<vminsert> 2003
Additional information: