How to configure Telegraf to write to InfluxDB 3 Core

Configuring Telegraf to write to InfluxDB 3 Core sends collected host or application metrics into a Core database. This is useful after deploying a new Core server, adding an agent to a host, or moving metrics ingestion to InfluxDB 3 while keeping Telegraf's plugin-based collection model.

Current Telegraf releases include the outputs.influxdb_v3 plugin for InfluxDB 3 Core and InfluxDB 3 Enterprise. The output sends line protocol over the InfluxDB 3 HTTP API, and the database setting selects the Core database that receives each flushed batch.

Use a token with write permission, keep the token outside the configuration file, and test a single Telegraf collection before restarting a long-running service. For InfluxDB OSS v2, InfluxDB Cloud TSM, or older Telegraf agents, use outputs.influxdb_v2 with organization and bucket instead of the v3 database setting.

1. Set the InfluxDB write token for the current shell.

   $ export INFLUX_TOKEN='INFLUXDB_WRITE_TOKEN'

   Use a token scoped for writes to the target database. Keep the real token out of shared transcripts, screenshots, issue comments, and committed files.

2. Generate a Telegraf configuration with a CPU input and InfluxDB 3 output.

   $ telegraf --input-filter cpu --output-filter influxdb_v3 config > telegraf.conf

   The generator creates complete plugin sections for inputs.cpu and outputs.influxdb_v3. Keep existing production inputs in place when Telegraf already collects real metrics.

3. Open the generated Telegraf configuration.

   $ vi telegraf.conf

4. Set the InfluxDB 3 output values.

   telegraf.conf

     urls = ["http://127.0.0.1:8181"]
     token = "${INFLUX_TOKEN}"
     database = "sensors"

   Replace http://127.0.0.1:8181 with the Core URL that Telegraf reaches, and replace sensors with the target database.

5. Set the smoke-test CPU input values.

   telegraf.conf

     percpu = false
     totalcpu = true
     collect_cpu_time = false

6. Install the edited configuration as the active Telegraf file.

   $ sudo install -m 640 telegraf.conf /etc/telegraf/telegraf.conf

   Packaged Linux installs normally use /etc/telegraf/telegraf.conf as the main file and /etc/telegraf/telegraf.d as the config directory. If the service uses a custom --config or --config-directory path, install or edit that active path instead.

7. Store the token where the packaged Telegraf service can read it.

   $ sudo vi /etc/default/telegraf

   /etc/default/telegraf

   INFLUX_TOKEN="INFLUXDB_WRITE_TOKEN"

   DEB and RPM packages read /etc/default/telegraf for environment variables. Use your service manager or Telegraf secret store when your deployment keeps agent credentials somewhere else.

8. Restrict the Telegraf environment file.

   $ sudo chmod 600 /etc/default/telegraf

   The environment file contains a credential. Limit read access to administrators and the service startup path.

9. Test that Telegraf can load the input and configuration.

   $ telegraf --config /etc/telegraf/telegraf.conf --test
   2026-06-20T04:01:20Z I! Loading config: /etc/telegraf/telegraf.conf
   2026-06-20T04:01:20Z I! Loaded inputs: cpu
   2026-06-20T04:01:20Z W! Outputs are not used in testing mode!
   > cpu,cpu=cpu-total,host=metrics-host usage_idle=99.25,usage_system=0.25,usage_user=0.25 1781928081000000000

   --test proves the input plugin emits metrics and the file parses, but it intentionally does not send data to configured outputs.

10. Run one Telegraf collection against the InfluxDB output.

    $ telegraf --config /etc/telegraf/telegraf.conf --once
    2026-06-20T04:01:21Z I! Loading config: /etc/telegraf/telegraf.conf
    2026-06-20T04:01:21Z I! Loaded inputs: cpu
    2026-06-20T04:01:21Z I! Loaded outputs: influxdb_v3
    2026-06-20T04:01:22Z I! [agent] Stopping running outputs

    --once collects one batch and sends it to the configured output, so authentication, URL reachability, and database selection are tested before the service restart.

11. Restart the Telegraf service after the one-shot write succeeds.

    $ sudo systemctl restart telegraf

    Skip this step when Telegraf is launched by a container, supervisor, or custom unit. Restart through the runtime that owns the long-running agent process.

12. Confirm the service is running.

    $ systemctl is-active telegraf
    active

13. Set the query token for the InfluxDB CLI check.

    $ export INFLUXDB3_AUTH_TOKEN="$INFLUX_TOKEN"

14. Set the InfluxDB host URL when the server is not on the default local listener.

    $ export INFLUXDB3_HOST_URL=http://127.0.0.1:8181

15. Query the database for the metric written by Telegraf.

    $ influxdb3 query --database sensors "SELECT time, cpu, usage_idle FROM cpu ORDER BY time DESC LIMIT 3"
    +---------------------+-----------+-------------------+
    | time                | cpu       | usage_idle        |
    +---------------------+-----------+-------------------+
    | 2026-06-20T04:01:22 | cpu-total | 99.75247524153338 |
    +---------------------+-----------+-------------------+

    A returned cpu row proves the output plugin flushed a metric into the sensors database.
    Related: How to run an SQL query in InfluxDB 3 Core

16. Remove the temporary working copy after the active configuration is installed.

    $ rm telegraf.conf