Recipe

InfluxDB primer

InfluxDB is a purpose-built time-series database optimized for high-write-throughput telemetry, metrics, and event data. This primer walks Meridian operators through the schema model, the line-protocol wire format, and how to wire ingestion into a production observability stack without falling into the cardinality trap.

1. Schema fundamentals

Every InfluxDB point lives inside a measurement (the rough equivalent of a table) and is described by tags (indexed string dimensions), fields (the actual numeric or string payload), and a nanosecond-precision timestamp. Tags are cheap to filter on but expensive to add. Fields are the opposite: cheap to store, but you cannot use them in WHERE efficiently.

Treat tags as enums with bounded cardinality such as region, service, or environment. Push high-cardinality identifiers like request IDs into fields instead.

2. Line protocol wire format

Writes use a compact text format: measurement, comma-separated tags, a space, comma-separated fields, a space, then the timestamp. Below is a representative payload that Meridian agents emit when reporting gateway latency back to the central InfluxDB cluster.

# measurement,tag_set field_set timestamp
gateway_latency,region=us-east,svc=router p50=12.4,p99=88.1 1735689600000000000
gateway_latency,region=eu-west,svc=router p50=18.7,p99=102.3 1735689600000000000
gateway_errors,region=us-east,svc=router count=3i 1735689600000000000

# curl example - direct write to v2 API
curl -XPOST "https://influx.meridian.local/api/v2/write?org=meridian&bucket=metrics" \
  -H "Authorization: Token $INFLUX_TOKEN" \
  --data-binary @batch.lp

3. Cardinality and retention

Series cardinality is the product of all unique tag combinations across a measurement. Past a few million series the in-memory TSI index degrades and query latency climbs sharply. Audit cardinality weekly with SHOW SERIES CARDINALITY and split offending workloads into separate buckets with shorter retention policies.

Pair raw buckets (7 days) with downsampled buckets (90 days, 1y) using continuous Flux tasks. Meridian dashboards then query the cheapest bucket that satisfies the time window of the panel.