写入 API

集群版和单机版在 API URL 上的主要区别，就是集群版在 URL Path 上对查询和写入都增加了前缀，用insert和select区分了查询和写入 Path，同时支持了租户。

集群版写入 API 的 URL 格式为:

http://<vminsert>:8480/insert/<accountID>/<suffix>

这里：

<accountID> 是一个32位整型数字，代表数据写入的控件（即租户）。
- 它也可以设置为accountID:projectID，这里的projectID也是一个32位整型。如果projectID没有指定，则默认为0。更多内容请阅读多租户。
- <accountID>也可以写成字符串multitenant，例如http://<vminsert>:8480/insert/multitenant/<suffix>，使用这种 URL 写入的数据，系统会从数据 Label 中寻找vm_account_id和vm_project_id信息，将 Label 值作为租户信息。更多内容请阅读多租户
<suffix> 就是单机版中的 URL Path，下面会一一给出。

导入

JSON

curl -H 'Content-Type: application/json' --data-binary "@filename.json" -X POST http://localhost:8428/api/v1/import
curl -H 'Content-Encoding: gzip' -X POST http://destination-victoriametrics:8428/api/v1/import -T exported_data.jsonl.gz

将 Content-Encoding: gzip 的 HTTP 请求头传递给 /api/v1/import，用于导入经过压缩的数据：

curl -H 'Content-Type: application/json' --data-binary "@filename.json" -X POST http://<vminsert>:8480/insert/0/prometheus/api/v1/import

JSON 格式如下所示，从/api/v1/export导出的就是这种格式:

{"metric":{"__name__":"up","job":"node_exporter","instance":"localhost:9100"},"values":[0,0,0],"timestamps":[1549891472010,1549891487724,1549891503438]}
{"metric":{"__name__":"up","job":"prometheus","instance":"localhost:9090"},"values":[1,1,1],"timestamps":[1549891461511,1549891476511,1549891491511]}

CSV

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'

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'

Native

导入二进制数据，该二进制数据是通过/api/v1/export/native接口导出的。

curl -X POST http://localhost:8428/api/v1/import/native -T filename.bin

curl -X POST http://<vminsert>:8480/insert/0/prometheus/api/v1/import/native -T filename.bin

Prometheus

Exposition Text Format

想 VictoriaMetrics 中导入 Prometheus 文本格式指标：

curl -d 'metric_name{foo="bar"} 123' -X POST http://localhost:8428/api/v1/import/prometheus

curl -d 'metric_name{foo="bar"} 123' -X POST http://<vminsert>:8480/insert/0/prometheus/api/v1/import/prometheus

Remote Write

prometheus和prometheus/api/v1/write两个接口都可以处理 Prometheus Remote Write 数据

http://localhost:8428/prometheus
# 或
http://localhost:8428/prometheus/api/v1/write

http://<vminsert>:8480/insert/0/prometheus
# 或
http://<vminsert>:8480/insert/0/prometheus/api/v1/write

OpenTelemetry

VictoriaMetrics 不支持 OpenTelemetry 的 Stream 写入，只支持单次的 Protobuf 编码的 HTTP 写入。

http://localhost:8428/opentelemetry/v1/push

http://<vminsert>:8480/insert/0/opentelemetry/v1/push

DataDog

VictoriaMetrics 支持接收 DataDog agent 发送出的数据, DogStatsD 和 DataDog Lambda Extension，使用/datadog/api/v2/series『submit metrics』或使用/datadog/api/beta/sketches『sketches』。

http://localhost:8428/datadog

http://<vminsert>:8480/insert/0/datadog

V1 Format

/datadog/api/v1/series

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

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'

V2 Format

/datadog/api/v2/series

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

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'

其他

DataDog Agent

DataDog agent 支持通过环境变量DD_DD_URL配置发送地址，或者在配置文件的dd_url部分配置

使用环境变量配置发送地址：

DD_DD_URL=http://victoriametrics:8428/datadog

在配置文件中配置发送地址，只需在配置文件中加入下面一行内容：

dd_url: http://victoriametrics:8428/datadog

vmagent 组件也可以接收 DataDog metrics 数据格式。

数据双发

DataDog 允许通过环境变量DD_ADDITIONAL_ENDPOINTS添加额外的地址实现数据双发，让它把 metrics 发送给其他额外的地址，也可以通过配置文件中的additional_endpoints配置项设置。

使用环境变量配置额外的发送地址：

DD_ADDITIONAL_ENDPOINTS='{\"http://victoriametrics:8428/datadog\": [\"apikey\"]}'

使用配置文件设置额外的发送地址：

additional_endpoints:
  "http://victoriametrics:8428/datadog":
  - apikey

Serverless Plugin

禁用日志能力(因为 VictoriaMetrics 不支持日志写入) ，且在serverless.yaml中自定义发送地址：

custom:
  datadog:
    enableDDLogs: false             # Disabled not supported DD logs
    apiKey: fakekey                 # Set any key, otherwise plugin fails
provider:
  environment:
    DD_DD_URL: <<vm-url>>/datadog   # VictoriaMetrics endpoint for DataDog

InfluxDB

V2 Format

curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST http://localhost:8428/api/v2/write

curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST http://<vminsert>:8480/insert/0/influx/api/v2/write

V1 Format

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://<vminsert>:8480/insert/0/influx/write

Telegraf

使用http://<victoriametrics-addr>:8428地址代替 agent 配置中的 InfluxDB 地址。例如，把下面几行放到 telegraf 的配置中，那么它就会将数据发送给 VictoriaMetrics：

[[outputs.influxdb]]
  urls = ["http://<victoriametrics-addr>:8428"]

另一个办法是使用-influxListenAddr参数开启针对 InfluxDB Line Protocol 的 TCP/UDP 服务，这样就可以将 InfluxDB Line Protocol 的行数据流式的发送给这个 TCP/UDP 地址了。

VictoriaMetrics 对接收到的 InfluxDB 数据做了如下转换：

除非 InfluxDB 行中已经存在名为db的 Label 了，否则 url 中的db参数会被注入到数据 Label 中。db是用于表示数据库的默认 Label 名，可以通过-influxDBLabel启动参数将db替换成其他名称。
VictoriaMetrics 是没有数据库概念的，如果要实现严格的数据隔离，请阅读多租户相关信息。
Influx Field 名字会被追加上{measurement}{separator}前缀，然后作为 Metric 名称，其中{separator}默认是下划线_。可以使用-influxMeasurementFieldSeparator参数自定义。如果{measurement}为空或者使用了-influxSkipMeasurement参数，则直接使用 InfluxDB 的 Field 名称作为 Metric 名称。 -influxSkipSingleField表示如果一行数据里只有一个 field，则直接使用 measurement 作为 Metric 名称。
Influx Field 值会被作为 Timeseries 的值。
Influx Tags 会被作为 Prometheus Labels.
如果设置了-usePromCompatibleNaming参数，则所有的 Metric 名和 Label 名都会被格式化成 Prometheus 兼容的命名规则，并使用下划线_代替非法字符。例如如果 Metric 名或 Label 名是foo.bar-baz/1，则会被格式化成foo_bar_baz_1。

例如，下面是一行 InfluxDB 协议的数据：

foo,tag1=value1,tag2=value2 field1=12,field2=40

该行数据内容将会被转换为如下的 Prometheus 格式数据：

foo_field1{tag1="value1", tag2="value2"} 12
foo_field2{tag1="value1", tag2="value2"} 40

使用 /api/v1/export 接口查询数据，会返回如下内容：

curl -G 'http://localhost:8428/api/v1/export' -d 'match={__name__=~"measurement_.*"}'

# 结果
{"metric":{"__name__":"measurement_field1","tag1":"value1","tag2":"value2"},"values":[123],"timestamps":[1560272508147]}
{"metric":{"__name__":"measurement_field2","tag1":"value1","tag2":"value2"},"values":[1.23],"timestamps":[1560272508147]}

注意 InfluxDB Line Protocol 期望的时间戳是纳秒级，而 VictoriaMetrics 是以毫秒的精度存储。系统允许使用秒、微妙或纳秒的精度写入数据，VictoriaMetrics 会自动转换成毫秒精度存储。

可在写入 URL /write 加上extra_label参数为所有写入数据注入额外的 Label。比如使用/write?extra_label=foo=barURL写数据，系统会为每条写入的 Metric 数据追加{foo="bar"}Label

一些 Telegraf 的插件如 fluentd, Juniper/open-nti 或 Juniper/jitmon 会发送SHOW DATABASES查询到/query来获取数据库名字列表，并期望返回结果中包含特定的数据库名。可以将逗号分割的多个数据库名作为-influx.databaseNames参数。

OpenTSDB

TCP

使用-opentsdbListenAddr参数开启 OpenTSDB 数据接收器。

echo "put foo.bar.baz `date +%s` 123 tag1=value1 tag2=value2" | nc -N localhost 4242

echo "put foo.bar.baz `date +%s` 123  tag1=value1 tag2=value2" | nc -N http://<vminsert> 4242

HTTP

使用-opentsdbHTTPListenAddr参数开启 OpenTSDB 数据 HTT P接收器。

curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]' http://localhost:4242/api/put

curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]' http://<vminsert>:8480/insert/42/opentsdb/api/put

Graphite

使用-graphiteListenAddr参数开启 Graphite 数据接收器。

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 http://<vminsert> 2003

StatD

使用-graphiteListenAddr参数可以开启 Graphite 支持；比如下面的命令使 VictoriaMetrics 通过监听2003TCP/UDP端口来接收 Graphite 数据。

/path/to/victoria-metrics-prod -graphiteListenAddr=:2003

将上面的地址配置到 Graphite 兼容的 agent 上。例如，在StatD的配置中设置graphiteHost配置项。

下面的命令是使用nc命令将数据以 Graphite 文本协议写入到本地的 VictoriaMetrics 中：

echo "foo.bar.baz;tag1=value1;tag2=value2 123 `date +%s`" | nc -N localhost 2003

使用-graphite.sanitizeMetricName参数让 VictoriaMetrics 将写入的 Graphite metrics 使用 Prometheus 命名规范进行一定的转换。当使用该参数时，数据的修改规则如下：

删除多余的点.符号，比如metric..name => metric.name
对于没有匹配a-zA-Z0-9:_.的字符，统一转换成下划线_
VictoriaMetrics 将数据写入时间作为时序数据的时间

任意数量的数据可使用\n作为分割，一次性发送进来。然后在通过/api/v1/export接口查询数据：

curl -G 'http://localhost:8428/api/v1/export' -d 'match=foo.bar.baz'

{"metric":{"__name__":"foo.bar.baz","tag1":"value1","tag2":"value2"},"values":[123],"timestamps":[1560277406000]}

Push vs Pull

写入 API

导入

JSON

CSV

Native

Prometheus

Exposition Text Format

Remote Write

OpenTelemetry

DataDog

V1 Format

V2 Format

其他

DataDog Agent

数据双发

Serverless Plugin

更多细节

InfluxDB

V2 Format

V1 Format

Telegraf

OpenTSDB

TCP

HTTP

Graphite

StatD