Skip to content
Documentation Prelude Collector 1.0.0

InfluxDB output

Write collected telemetry to an InfluxDB v2 instance via the non-blocking write API. Tags, fields, batching, and example configuration.

The InfluxDB output writes collected telemetry to an InfluxDB v2 instance using the non-blocking write API. 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".

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.

Field JSON key Type Required Default Description
URL url string Yes — InfluxDB server URL, e.g. http://influxdb.example.com:8086
Token token string Yes — InfluxDB API token. Sensitive — masked as "********" in API responses.
Organization org string Yes — InfluxDB organization name
Bucket bucket string Yes — Target bucket name
Batch size batch-size uint No client default Records to buffer before flushing
Flush interval flush-interval int No client default Maximum time between flushes (ms)

token is stored encrypted. When updating the configuration, sending "" or "********" for token preserves the existing value — only re-supply the token when it has actually changed.

Authentication

InfluxDB v2 uses API tokens. Create one in your InfluxDB instance with write access to the target bucket and supply it as token. There is no separate username/password mode — the v1 compatibility API is not used.

Configuration example

{
  "enabled": true,
  "config": {
    "url": "http://influxdb.example.com:8086",
    "token": "<your-api-token>",
    "org": "prelude",
    "bucket": "collector",
    "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 runs four sequential checks (reachable, authenticated, org-valid, bucket-valid) and short-circuits on the first failure.

Limitations

  • Only InfluxDB v2 is supported (v1 line protocol over the v1 compatibility API is not configured here).
  • 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

Filtering by: