Kapacitor

Last reviewed Sep 13, 2026 · 777 words

Run Kapacitor if you already have an InfluxDB 1.x server full of Telegraf metrics and you want alerts that fire on that data with sub-second latency. Do not adopt it for a new stack in 2026. InfluxData replaced it in the 2.x line with built-in tasks, and most homelabs that want alerting on time series get more from Grafana's unified alerting with far less to learn. That is the honest position on a 2,377-star, MIT-licensed Go daemon that is still perfectly functional and still the most capable stream processor in its family.

Where it sits in the TICK stack

The letters are Telegraf (collection), InfluxDB (storage), Chronograf (UI), and Kapacitor (processing and alerting). Kapacitor subscribes to InfluxDB and receives every point as it is written, or it runs batch queries on a schedule, and it evaluates scripts against that stream. When a condition holds, it pushes to a handler: Slack, Telegram, PagerDuty, OpsGenie, an arbitrary HTTP POST, an executable on disk, or a write back into InfluxDB. It listens on port 9092 and the Docker image is simply kapacitor:1.7 at last check, with a single kapacitor.conf that points at the InfluxDB URL.

The subscription model is the part worth understanding. Because InfluxDB 1.x forwards writes to Kapacitor as they land, a threshold alert triggers within milliseconds of the offending data point, not on the next poll. Prometheus-style evaluation runs on an interval measured in tens of seconds. For a homelab that difference almost never matters. For someone alerting on a CNC machine or a fermentation tank, it does.

TICKscript is a small language with a real learning curve

Alerts are defined in TICKscript, a pipeline DSL where each node feeds the next. A working CPU alert looks like this:

stream
    |from()
        .measurement('cpu')
        .where(lambda: "cpu" == 'cpu-total')
    |window()
        .period(1m)
        .every(10s)
    |mean('usage_idle')
    |alert()
        .crit(lambda: "mean" < 10)
        .message('CPU on {{ index .Tags "host" }} is pegged')
        .slack()

Load it with kapacitor define cpu_alert -tick cpu.tick -dbrp telegraf.autogen and kapacitor enable cpu_alert. The syntax is readable once you have written three of these, and the node set is broad: joins across measurements, derivative and moving-average nodes, a user-defined-function hook for running Python or Go anomaly detectors, and template tasks so 40 hosts share one script with different variables. None of it transfers anywhere else. Flux replaced it inside InfluxData and nobody outside adopted it, so the hours you spend on TICKscript are hours on a dead-end skill.

Alert routing is the strong suit

The thing Kapacitor still does better than Grafana is state handling on the alert itself. Each alert node tracks OK, INFO, WARNING, and CRITICAL levels, fires on level changes rather than on every evaluation, and supports .stateChangesOnly() so a flapping disk does not page you 30 times an hour. Topics and handlers, defined in YAML files outside the scripts, let you route all critical alerts to one channel and all warnings to another without editing every task. Alertmanager does this too, but Kapacitor was doing it in 2016 with a single binary and no sidecars.

Resource use is modest. Idle it sits near 100 MB of RAM; with 20 stream tasks watching a Telegraf feed from 10 hosts I have seen it hold around 400 MB, which matches the 512 MB floor listed for it.

The 2.x problem is the real reason to hesitate

InfluxDB 2.x moved alerting into the database as Flux tasks and checks, and Kapacitor became optional. InfluxDB 3 dropped Flux entirely. Kapacitor can connect to a 2.x instance through the 1.x compatibility API, but the setup is fiddly and the project's own documentation treats it as a migration bridge rather than a destination. If your InfluxDB is 1.8 and staying there, Kapacitor is the native fit. If you are on 2.x, use its built-in checks. If you are planning a fresh stack, Prometheus with Alertmanager or any datasource under Grafana alerting gets you rules, silences, and contact points with a community that is still growing.

What I'd do

Keep Kapacitor exactly where it already runs: next to an InfluxDB 1.8 box that Telegraf has been feeding for years, doing threshold and deadman alerts with stateChangesOnly on, routed to one Slack or Telegram handler. Do not write new anomaly-detection UDFs for it. When that InfluxDB finally gets rebuilt, put the metrics in Prometheus or InfluxDB 3 and do the alerting in Grafana, which will already be on the box drawing the graphs.