InfluxDB

Databases Analytics

Synopsis

Creates an InfluxDB target that writes each record as one point of InfluxDB line protocol, over HTTP. It writes to InfluxDB 1.x, 2.x and 3, through the v1, v2 or v3 write API. Records from the InfluxDB device keep their measurement, tags and fields, and any other record is mapped to a point.

Schema

- name: <string>
  description: <string>
  type: influxdb
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <integer>
    api_version: <string>
    database: <string>
    retention_policy: <string>
    org: <string>
    bucket: <string>
    token: <string>
    username: <string>
    password: <string>
    measurement_field: <string>
    measurement: <string>
    tags: <string[]>
    fields: <string[]>
    batch_size: <integer>
    max_bytes: <integer>
    timeout: <integer>
    field_format: <string>
    tls:
      status: <boolean>
      verify: <boolean>
      ca_name: <string>
      cert_name: <string>
      key_name: <string>
      passphrase: <string>
      server_name: <string>
      min_tls_version: <string>
      max_tls_version: <string>
    debug:
      status: <boolean>
      dont_send_logs: <boolean>

Configuration

The following fields are used to define the target:

Field	Required	Default	Description
name	Y		Target name
description	N	-	Optional description
type	Y		Must be influxdb
pipelines	N	-	Optional post-processor pipelines
status	N	true	Enable/disable the target

Connection

Field	Required	Default	Description
address	Y	-	Host name or IP address of the server
port	N	8086, or 8181 for v3	Port of the server
api_version	N	v2	The write API: v1, v2 or v3. See API Versions
token	N*	-	The token the target signs in with. Required for v2
username	N	-	The user the target signs in as with HTTP Basic, when no token is set
password	N	-	Password for that user
timeout	N	30	Seconds one request may take. At least 1

Where the Points Land

Field	Required	Default	Description
database	N*	-	The database. Required for v1 and v3
retention_policy	N	-	v1 only. The retention policy the points are written under. When unset, the database's default policy
org	N*	-	v2 only. The organization the bucket belongs to, by name or ID. Required for v2
bucket	N*	-	v2 only. The bucket. Required for v2

Point Mapping

These four fields apply to every record that the InfluxDB device did not write. See How a Record Becomes a Point.

Field	Required	Default	Description
measurement_field	N	event.dataset	The record field whose text names the measurement
measurement	N	record	The measurement when that field is missing or empty
tags	N	-	The record fields that become tags. A list, or one text with the paths separated by commas
fields	N	-	The record fields that become fields. When empty, every number and boolean in the record

Delivery

Field	Required	Default	Description
batch_size	N	5000	The most lines in one request
max_bytes	N	10485760 (10 MB)	The most bytes of line protocol in one request, before compression
field_format	N	-	Converts each record to a format such as ECS or OCSF before it is mapped. See applicable Normalization section

note

max_bytes caps the size of a single request body or batch. It behaves differently from max_size on the file-writing targets, and the difference is easy to get wrong:

• An explicit max_bytes: 0 IS honoured and removes the ceiling on targets that have no ceiling of their own. The value is read with Int64, which returns what you wrote — unlike max_size, which is read with MustInt64 and silently substitutes its default for a zero. Where a target has a fixed ceiling of its own, its page says so and a zero is clamped to that ceiling instead.
• A negative value is rejected at configuration time with max_bytes must not be negative.

The ceiling is validated when the target is built and enforced again on every batch, so a value the receiving service will refuse fails early rather than per request.

TLS

Field	Required	Default	Description
tls.status	N	false	Use HTTPS. TLS stays off unless this is true

TLS material is resolved through the shared client builder, so these keys mean the same thing on every target that uses it. They are nested under a tls: block.

Field	Required	Default	Description
tls.verify	N	true	Verify the server certificate. On by default — set it to false only to accept an untrusted certificate, and only where you control the network path
tls.server_name	N	-	SNI hostname override for the handshake. Use it when the certificate's name does not match the address you connect to
tls.ca_name	N	-	CA bundle used to verify the server certificate. When unset the host trust store is used; when set it replaces the host trust store rather than adding to it
tls.cert_name	N*	-	Client certificate, for mutual TLS
tls.key_name	N*	-	Client private key, for mutual TLS
tls.passphrase	N	-	Passphrase for an encrypted client private key
tls.min_tls_version	N	tls1.2	Lowest protocol version accepted (tls1.0, tls1.1, tls1.2, tls1.3)
tls.max_tls_version	N	tls1.3	Highest protocol version accepted (tls1.0, tls1.1, tls1.2, tls1.3)

* cert_name and key_name are individually optional but must be supplied together — a certificate without its key, or a key without its certificate, is a configuration error.

Scheduling

See Scheduling and Pool Behavior for interval and cron fields shared by all targets.

Debug Options

Field	Required	Default	Description
debug.status	N	false	Enable debug logging
debug.dont_send_logs	N	false	Process logs but don't send to target (testing)

Details

The InfluxDB target writes each record as one point of InfluxDB line protocol, and sends each batch in one HTTP request. The body is gzip compressed. The target sends no precision setting, because every InfluxDB write API reads nanoseconds by default.

The same sender serves the Amazon Timestream for InfluxDB, VictoriaMetrics, GreptimeDB and QuestDB targets, so they map records the same way.

API Versions

api_version	Product	Default port	Where the points land	Sign-in
v1	InfluxDB 1.x, and InfluxDB 2 and 3 through their v1 API	8086	database (required) and retention_policy	A token, or else username and password over HTTP Basic
v2 (default)	InfluxDB 2.x	8086	org and bucket (both required)	A token (required)
v3	InfluxDB 3	8181	database (required)	A token, or else username and password over HTTP Basic

With api_version: v1, InfluxDB 1.x signs in with username and password. InfluxDB 2 and 3 can use the v1 API with an API token.

How a Record Becomes a Point

• A record that the InfluxDB device wrote keeps its measurement, its tags and its fields. Each field keeps its type: a float, an integer, an unsigned integer, a boolean or a string. The point mapping fields do not apply to it.
• Any other record is mapped. The measurement is the text at measurement_field, or measurement when that field is missing or empty. Each field that tags lists becomes a tag, and each field that fields lists becomes a field, named by its path. When fields is empty, every number in the record becomes a float field and every boolean becomes a boolean field. Numbers in arrays, the record's time and the fields used as tags are left out.
• The time of the point is the record's @timestamp, in nanoseconds. A record without one gets the server's time.
• A record that gives no field is skipped and counted as dropped. The Director logs a warning when no record of a batch gives a field.

Prerequisites

1. A running InfluxDB server, reachable from the Director host
2. For v2, the organization and the bucket, already created, and an API token that can write to the bucket
3. For v1 and v3, the database, already created

Examples

InfluxDB 2

Writing to a bucket through the v2 API, the default:

targets:
  - name: influxdb_metrics
    type: influxdb
    properties:
      address: "influxdb.example.com"
      org: "my-org"
      bucket: "metrics"
      token: "your-api-token"
      tls:
        status: true

api_version and port are left out, so they default to v2 and 8086. With tls.status: true the target sends the token over HTTPS rather than in cleartext. The server must accept HTTPS on its port.

InfluxDB 1.x

Writing to a database and a retention policy through the v1 API over HTTPS, signing in with a user name and a password:

targets:
  - name: influxdb_v1
    type: influxdb
    properties:
      address: "influxdb.example.com"
      api_version: "v1"
      database: "telegraf"
      retention_policy: "autogen"
      username: "datastream"
      password: "secret"
      tls:
        status: true

InfluxDB 3 over HTTPS, with Tags

Writing to an InfluxDB 3 database over HTTPS, with two record fields as tags and one as the only field:

targets:
  - name: influxdb_v3
    type: influxdb
    properties:
      address: "influxdb3.example.com"
      api_version: "v3"
      database: "observability"
      token: "your-api-token"
      tags:
        - host.name
        - observer.name
      fields:
        - metric.value
      tls:
        status: true

port is left out, so it defaults to 8181, the port of the v3 API.

Troubleshooting

Situation	Result
The server refuses the data (400, 413 or 422)	The batch is tried up to four times, then dropped. A 400 or 422 answer can mean a partial write: the server keeps the points it accepted, and a point sent again with the same measurement, tags and time merges its fields into the stored point
Sign-in fails (401 or 403), the database or bucket does not exist yet (404), the server is busy (429), a server error (5xx), or the connection fails	The batch is retried
The server answers with a redirect	Counted as a failure: the target does not follow redirects

Records are dropped although nothing fails

Skipped 1000 of 1000 records for metrics. Each one gave no field: it has no number or boolean, or no value at the paths that fields lists.

Cause: the records give no field. Either they hold no number or boolean, or none of the paths that fields lists has a value in them.

Fix: list the record fields that carry the values in fields, or leave fields empty to write every number and boolean.

Configuration errors

These stop the target from starting:

Reason text	Fix
address is required for influxdb target	Set address
api_version must be one of v1, v2, v3 for influxdb target, got "..."	Set api_version to v1, v2 or v3, or leave it out to use v2
org is required for influxdb target with api_version v2	Set org
bucket is required for influxdb target with api_version v2	Set bucket
token is required for influxdb target with api_version v2	Set token
database is required for influxdb target with api_version ...	Set database for v1 and v3
timeout must be at least 1 second for influxdb target, got ...	Set timeout to 1 or more
batch_size must be a whole number greater than 0 for influxdb target, got ...	Use a whole number of at least 1, or leave batch_size out to use 5000
failed to build TLS config: ...	The rest of the line names the TLS setting at fault