---

name: influxdb description: >- InfluxDB is an open-source time-series database for metrics, events and sensor data. Use when a user needs to run InfluxDB 2 or InfluxDB 3 Core, create buckets, databases and API tokens, write line protocol, query with Flux, SQL or InfluxQL, set retention periods, downsample data with tasks, or alert on thresholds. license: Apache-2.0 compatibility: "InfluxDB OSS 2.9 with the influx CLI 2.8 (Flux), or InfluxDB 3 Core 3.11 (SQL and InfluxQL)" metadata: author: terminal-skills version: "1.1.0" category: devops repository: https://github.com/influxdata/influxdb tags: ["influxdb", "time-series", "flux", "metrics", "monitoring"]

InfluxDB

Overview

Configure InfluxDB for time-series data storage and analysis. Two generations are in use and they are not interchangeable:

• InfluxDB 2 (OSS 2.9.1, port 8086): buckets, the Flux language, tasks, checks, a built-in UI, the influx CLI. Tasks A–F below. Flux is in maintenance mode — still supported on 1.x and 2.x, never coming to 3.
• InfluxDB 3 Core (3.11.5, port 8181): databases and tables, SQL and InfluxQL, the influxdb3 CLI, no Flux and no tasks (a Python processing engine replaces them). Task G.

Instructions

Task A: Initial Setup and Configuration

# Deploy InfluxDB 2 with Docker. Pin the tag: `latest` is announced to move to InfluxDB 3 Core.
docker run -d --name influxdb \
  -p 8086:8086 \
  -v influxdb_data:/var/lib/influxdb2 \
  -v influxdb_config:/etc/influxdb2 \
  -e DOCKER_INFLUXDB_INIT_MODE=setup \
  -e DOCKER_INFLUXDB_INIT_USERNAME=admin \
  -e DOCKER_INFLUXDB_INIT_PASSWORD="$INFLUXDB_ADMIN_PASSWORD" \
  -e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN="$INFLUX_TOKEN" \
  -e DOCKER_INFLUXDB_INIT_ORG=myorg \
  -e DOCKER_INFLUXDB_INIT_BUCKET=metrics \
  -e DOCKER_INFLUXDB_INIT_RETENTION=30d \
  influxdb:2.9

# /etc/influxdb2/config.yml — InfluxDB 2 options are flat keys, the same names as the influxd flags.
# 1.x-style sections ([http], [logging]) make influxd refuse to start.
# Keep both paths and use YAML with the Docker image: without them data lands outside the volume,
# and its entrypoint misreads a TOML bolt-path, re-runs setup and the container exits on restart.
bolt-path: /var/lib/influxdb2/influxd.bolt
engine-path: /var/lib/influxdb2/engine
http-bind-address: ":8086"
log-level: info
storage-cache-snapshot-memory-size: 26214400
storage-max-concurrent-compactions: 2
reporting-disabled: true

# Point the influx CLI at the server once; later commands need no --host or --token
influx config create --config-name production \
  --host-url http://localhost:8086 --org myorg --token "$INFLUX_TOKEN" --active

Task B: Bucket and Token Management

# Create buckets via CLI
influx bucket create --name infrastructure --retention 30d --org myorg
influx bucket create --name app-metrics --retention 90d --org myorg
influx bucket create --name downsampled --retention 365d --org myorg

# Scoped tokens take bucket IDs, not names
INFRA_ID=$(influx bucket list --name infrastructure --hide-headers | cut -f 1)
APP_ID=$(influx bucket list --name app-metrics --hide-headers | cut -f 1)

# Write-only token for Telegraf
influx auth create --org myorg --description "Telegraf write token" \
  --write-bucket "$INFRA_ID" --write-bucket "$APP_ID"

# Read-only token for Grafana
influx auth create --org myorg --description "Grafana read token" \
  --read-bucket "$INFRA_ID" --read-bucket "$APP_ID"

Copy the token from the auth create output immediately. Since 2.9.0 tokens are stored hashed: influx auth list no longer shows them and they cannot be recovered.

Task C: Write Data via API

# Write metrics using line protocol: measurement,tags fields timestamp
curl -X POST "http://localhost:8086/api/v2/write?org=myorg&bucket=app-metrics&precision=s" \
  -H "Authorization: Token ${INFLUX_TOKEN}" \
  -H "Content-Type: text/plain" \
  --data-binary '
http_requests,service=api-gateway,method=GET,status=200 count=1523,latency_ms=45.2 1790848800
http_requests,service=api-gateway,method=POST,status=201 count=234,latency_ms=120.5 1790848800
http_requests,service=payment,method=POST,status=500 count=3,latency_ms=5020.0 1790848800
queue_depth,service=order-processor queue_size=142,consumers=5 1790848800
'

A successful write returns HTTP 204 with an empty body. Numbers are floats unless suffixed with i (consumers=5i); a field keeps the type of its first write, and a later write with another type is rejected.

Task D: Flux Queries

// Query: CPU usage over last hour, grouped by host
from(bucket: "infrastructure")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_percent" and r.cpu == "cpu-total")
  |> aggregateWindow(every: 5m, fn: mean)
  |> yield(name: "cpu_usage")

// Query: Top 5 services by error count in last 24h
from(bucket: "app-metrics")
  |> range(start: -24h)
  |> filter(fn: (r) => r._measurement == "http_requests" and r._field == "count" and r.status =~ /^5/)
  |> group(columns: ["service"])
  |> sum()
  |> group()
  |> sort(columns: ["_value"], desc: true)
  |> limit(n: 5)

// Query: Calculate error rate percentage per service
errors = from(bucket: "app-metrics")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "http_requests" and r._field == "count" and r.status =~ /^5/)
  |> group(columns: ["service"])
  |> sum()

total = from(bucket: "app-metrics")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "http_requests" and r._field == "count")
  |> group(columns: ["service"])
  |> sum()

join(tables: {errors: errors, total: total}, on: ["service"])
  |> map(fn: (r) => ({ r with error_rate: (r._value_errors / r._value_total) * 100.0 }))

// Query: P95 latency with moving average
from(bucket: "app-metrics")
  |> range(start: -6h)
  |> filter(fn: (r) => r._measurement == "http_requests" and r._field == "latency_ms")
  |> aggregateWindow(every: 5m, fn: (tables=<-, column) =>
    tables |> quantile(q: 0.95, column: column))
  |> movingAverage(n: 6)

Save a query to a file and run it with influx query --file top-errors.flux.

Task E: Downsampling Tasks

// Task: Downsample infrastructure metrics hourly
option task = {name: "downsample-infra", every: 1h, offset: 5m}

from(bucket: "infrastructure")
  |> range(start: -task.every)
  |> filter(fn: (r) => r._measurement == "cpu" or r._measurement == "mem" or r._measurement == "disk")
  |> aggregateWindow(every: 1h, fn: mean)
  |> to(bucket: "downsampled", org: "myorg")

# Create the task, then check its runs and logs
influx task create --org myorg -f downsample-infra.flux
TASK_ID=$(influx task list --org myorg --hide-headers | grep downsample-infra | cut -f 1)
influx task run list --task-id "$TASK_ID" --limit 10
influx task log list --task-id "$TASK_ID"

Task F: Alerting and Checks

// Check: Alert when CPU exceeds 85%
import "influxdata/influxdb/monitor"
import "influxdata/influxdb/schema"

option task = {name: "cpu-alert", every: 1m}

check = {_check_id: "cpu-usage-high", _check_name: "High CPU", _type: "custom", tags: {}}

from(bucket: "infrastructure")
  |> range(start: -5m)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_percent" and r.cpu == "cpu-total")
  |> aggregateWindow(every: 5m, fn: mean, createEmpty: false)
  |> schema.fieldsAsCols()
  |> monitor.check(
    crit: (r) => r.usage_percent > 85.0,
    warn: (r) => r.usage_percent > 70.0,
    messageFn: (r) => "CPU at ${string(v: r.usage_percent)}% on ${r.host}",
    data: check,
  )

monitor.check() needs pivoted input (schema.fieldsAsCols(), so the thresholds read r.usage_percent, not r._value), a _time column (a bare mean() drops it) and a data record with _check_id, _check_name, _type and tags. Statuses land in the _monitoring bucket; read them with monitor.from(start: -1h). Sending them to Slack or PagerDuty takes a notification endpoint and rule, created in the UI under Alerts.

Task G: InfluxDB 3 Core

# Bind to localhost first: until an admin token exists, anyone who reaches the port can claim it
docker run -d --name influxdb3 -p 127.0.0.1:8181:8181 -v influxdb3_data:/var/lib/influxdb3 \
  influxdb:3-core influxdb3 serve --node-id host01 --object-store file --data-dir /var/lib/influxdb3/data

docker exec influxdb3 influxdb3 create token --admin     # printed once — store it
export INFLUXDB3_AUTH_TOKEN="$(cat ~/.secrets/influxdb3-admin-token)"

influxdb3 create database sensors --retention-period 30d
influxdb3 write --database sensors --precision s \
  'home,room=kitchen temp=22.4,hum=36.1,co=0i 1790848800'
influxdb3 query --database sensors \
  "SELECT room, avg(temp) AS avg_temp FROM home WHERE time >= now() - INTERVAL '1 hour' GROUP BY room"
influxdb3 query --database sensors --language influxql \
  "SELECT MEAN(temp) FROM home WHERE time > now() - 1h GROUP BY room"

The influxdb3 binary is both server and client; with Docker run client commands as docker exec -e INFLUXDB3_AUTH_TOKEN influxdb3 influxdb3 query .... Over HTTP: POST /api/v3/write_lp?db=sensors&precision=second and GET /api/v3/query_sql?db=sensors&q=...&format=json, both with Authorization: Bearer $INFLUXDB3_AUTH_TOKEN. Existing v2 writers keep working against /api/v2/write?bucket=sensors; /api/v2/query (Flux) does not exist.

Examples

Example 1: Keep raw metrics for 30 days and hourly averages for a year

User request: "Our InfluxDB 2 disk keeps filling up. Keep raw host metrics for 30 days and hourly averages for a year."

influx bucket update --id "$(influx bucket list --name infrastructure --hide-headers | cut -f 1)" --retention 30d
influx bucket create --name downsampled --retention 365d --org myorg
influx task create --org myorg -f downsample-infra.flux        # the Flux script from Task E
influx task run list --task-id "$(influx task list --hide-headers | grep downsample-infra | cut -f 1)" --limit 3

ID                TaskID            Status   ScheduledFor          StartedAt                       FinishedAt                      RequestedAt
1169ba833886e000  1169b9566f06e000  success  2026-10-01T10:00:00Z  2026-10-01T10:05:00.021826161Z  2026-10-01T10:05:00.124798932Z

After the first successful run, dashboards with ranges longer than 30 days must read from downsampled.

Example 2: Query the last hour with SQL on InfluxDB 3 Core

User request: "We just moved to InfluxDB 3. Show me the average temperature and the highest CO reading per room for the last hour."

influxdb3 query --database sensors \
  "SELECT room, avg(temp) AS avg_temp, max(co) AS max_co FROM home
   WHERE time >= now() - INTERVAL '1 hour' GROUP BY room ORDER BY room"

+---------+----------+--------+
| room    | avg_temp | max_co |
+---------+----------+--------+
| attic   | 19.0     | 0      |
| kitchen | 22.75    | 2      |
| living  | 21.9     | 1      |
+---------+----------+--------+

Add --format csv (or json, jsonl, parquet) for machine-readable output; date_bin(INTERVAL '10 minutes', time) in the SELECT and GROUP BY gives the SQL counterpart of Flux's aggregateWindow.

Guidelines

• Decide the generation first. Flux scripts, tasks, checks and dashboards do not run on InfluxDB 3; plan a rewrite to SQL or InfluxQL before migrating, and prefer InfluxQL or SQL for new work that must outlive 2.x.
• Pin Docker tags (influxdb:2.9, influxdb:3-core). InfluxData announced that latest will point to InfluxDB 3 Core, which would replace a 2.x container with an incompatible server.
• Upgrading 2.x to 2.9 hashes all existing tokens on first start. Record the operator token and any token you still need in plaintext before upgrading; --use-hashed-tokens=false keeps the old behaviour.
• Use separate buckets for raw and downsampled data with different retention periods
• Create scoped tokens with minimal permissions (write-only for collectors, read-only for dashboards)
• Keep tokens and the admin password in environment variables or a secrets manager. The influx CLI stores its connection configs, tokens included, in ~/.influxdbv2/configs (override with INFLUX_CONFIGS_PATH) — never commit that file.
• Use aggregateWindow() instead of window() + mean() for cleaner downsampled output
• Set precision in write requests to match your data granularity (seconds is usually sufficient)
• Use line protocol batch writes (multiple lines per request) to reduce HTTP overhead
• Keep tag values low-cardinality (hosts, regions, status codes). Request IDs or user IDs as tags multiply the series count and degrade InfluxDB 2.
• Monitor InfluxDB 2's own metrics at the /metrics endpoint for storage and query performance
• Install binaries from the package repositories or Docker. For a release archive from dl.influxdata.com, download the .sha256 file published next to it and compare its hash with the output of sha256sum on the archive before extracting (the InfluxDB 2 files name a build path, so sha256sum -c cannot find the file).