VictoriaMetrics/docs/url-examples.md
Andrii Chubatiuk 77c3bbf3fc
docs: updated guides structure, removed deprecated sort option ()
### 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)
2024-08-07 16:59:22 +02:00

20 KiB

weight title menu aliases
33 API examples
docs
parent weight identifier
victoriametrics 33 vm-api-examples
/url-examples.html

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

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

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

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