InfluxDB output

The InfluxDB output writes collected telemetry to an InfluxDB instance using the non-blocking write API. Both API versions are supported: v2 (organization / bucket / API token) and any 1.x release (1.0 through 1.8) using the classic database / retention-policy line-protocol endpoint with optional username and password. It is Prelude Collector's recommended Output for long-term time-series storage and Grafana dashboards. After the first mention this page refers to Prelude Collector as "the collector".

The version field selects the field set. Leave it blank or set it to v2 for a modern InfluxDB 2.x/OSS/Cloud instance; set it to v1 to target an InfluxDB 1.x server.

When to use

Pick InfluxDB when you need queryable, retained time-series data — for Grafana dashboards, downsampling and retention policies, or historical analysis. Pair it with NATS if you also need a real-time fan-out to other services. See Output selection for how it compares to Prometheus and Kafka.

How it works

Each record is converted to an InfluxDB line-protocol point and queued for asynchronous batched writing:

• Measurement — the model name (e.g. cpu, interface)
• Tags — device, device-id, key
• Fields — all top-level scalar values from the record's data payload
• Timestamp — the record's timestamp, or the current time if none is set

Nested maps and slices in the data payload are skipped — only top-level scalar values are written as fields.

Example point (line protocol)

cpu,device=router-01,device-id=42,key=cpu usage=45.2,cores=8 1704067200000000000

The Go integer-suffix form (cores=8i) only appears when a value arrives as a typed Go integer. Values that come from JSON unmarshalling — the common case for protocol parsers — are float64, so they land in the line protocol without the i suffix.

Connection settings

Configure this backend through PUT /api/v1/outputs/influxdb.

Shared fields (both versions):

InfluxDB v2 fields (version: "v2"):

InfluxDB 1.x fields (version: "v1"):

The version's secret — token (v2) or password (v1) — is stored encrypted. When updating the configuration, sending "" or "********" for that field preserves the existing value; only re-supply it when it has actually changed.

Authentication

v2 uses API tokens. Create one in your InfluxDB instance with write access to the target bucket and supply it as token.

1.x uses optional HTTP basic auth. Supply username and password when the server requires authentication; leave them blank for an unauthenticated 1.x server. Data is routed by database and, optionally, retention-policy.

Configuration example

InfluxDB v2:

{
  "enabled": true,
  "config": {
    "version": "v2",
    "url": "http://influxdb.example.com:8086",
    "token": "<your-api-token>",
    "org": "prelude",
    "bucket": "collector",
    "batch-size": 500,
    "flush-interval": 5000
  }
}

InfluxDB 1.x:

{
  "enabled": true,
  "config": {
    "version": "v1",
    "url": "http://influxdb.example.com:8086",
    "database": "collector",
    "retention-policy": "autogen",
    "username": "prelude",
    "password": "<your-influxdb-password>",
    "batch-size": 500,
    "flush-interval": 5000
  }
}

Apply it with:

export BASE="https://collector.example.com"
export TOKEN="<your-api-token>"

curl -s -X PUT "$BASE/api/v1/outputs/influxdb" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @influxdb-output.json

Bruno: 08 Outputs / Update output config

Behavior on failure

The Output uses InfluxDB's non-blocking write client. Points are buffered internally and flushed when either the batch size is reached or the flush interval expires.

Write errors are consumed from the client's error channel and logged — they do not block the collection pipeline. On graceful shutdown the backend calls Flush() to push any buffered points before closing.

Because writes are asynchronous and the per-batch Output() call returns success unconditionally, the InfluxDB backend's failures counter on /api/v1/outputs/metrics is always zero. Transient unreachability surfaces in the collector log channel and in the InfluxDB server's own logs, not in the collector's per-backend metric. Watch for influxdb output write warnings if you need a programmatic signal.

There is no on-disk buffer — points buffered in memory at the moment of a hard crash are lost.

To validate connectivity proactively, use POST /api/v1/outputs/influxdb/detect, which probes the configured instance and short-circuits on the first failure. For a v2 target it runs sequential reachable, authenticated, org-valid, and bucket-valid checks.

Limitations

• Only top-level scalar fields are written; nested maps and slices are dropped.
• Tag set is fixed (device, device-id, key); custom tags are not configurable per Output.
• There is no on-disk write-ahead buffer — in-flight points are lost on a hard crash before flush.
• Per-record retries are handled by the client library and are not separately tunable from this configuration.

See also

• Output backends
• Output selection
• Send data to Grafana