kanari agent

Continuous monitoring daemon with local logging or cloud alerts

Overview

kanari agent runs a continuous monitoring loop. On each cycle it collects metrics and either logs them locally (local mode) or sends them to the Kanari backend for persistent monitoring and alerts (API mode).

# Local mode — log metrics as structured JSON, no external calls
kanari agent --local

# API mode — after running kanari login, no flags needed
kanari agent

Stop with Ctrl+C or SIGTERM. The agent handles both gracefully.

---

Flags

Flag	Default	Description
--config, -c	—	Path to a YAML config file
--interval	15	Seconds between collection cycles
--local, -l	off	Log metrics locally, skip all API calls
--token	—	API key override (usually not needed after kanari login)
--no-color	off	Disable ANSI colors in log output

---

API key resolution

The agent finds your API key automatically in this order:

1. --token flag
2. KANARI_API_KEY environment variable
3. ~/.kanari/config — saved by kanari login ← recommended
4. api_key in your kanari.yaml

After running kanari login, you never need to set an API key manually.

---

Local mode

The best way to verify what the agent collects before connecting it to the backend.

kanari agent --local

Each cycle emits structured JSON to stdout:

{
  "timestamp": "2026-06-15T14:22:01Z",
  "total_pending": 47,
  "total_active": 6,
  "saturation_pct": 37.5,
  "redis_connected": true,
  "celery_connected": true,
  "queues": [
    {"name": "celery", "depth": 12, "oldest_task_age_seconds": 3.2},
    {"name": "emails", "depth": 35, "oldest_task_age_seconds": 88.1}
  ],
  "workers": [
    {"name": "api-worker", "active_tasks": 3, "concurrency": 8, "is_alive": true}
  ]
}

Pipe to jq for filtering:

kanari agent --local | jq '.queues[] | select(.depth > 100)'

---

API mode

API mode sends metrics to the Kanari backend on every cycle. The backend evaluates findings and sends Slack/email alerts when thresholds are breached.

# After kanari login — API key is loaded from ~/.kanari/config automatically
kanari agent

# Or with an explicit token
kanari agent --token sk_your_key_here

On startup the agent validates the API key. If invalid, it exits immediately with a clear error.

---

Running as a background service

systemd

# /etc/systemd/system/kanari-agent.service
[Unit]
Description=Kanari Agent — Celery queue monitor
After=network.target

[Service]
User=app
EnvironmentFile=/etc/kanari/env
ExecStart=/usr/local/bin/kanari agent --config /etc/kanari/kanari.yaml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now kanari-agent

Docker

FROM python:3.12-slim
RUN pip install kanari
CMD ["kanari", "agent", "--local"]

docker run -e REDIS_URL=redis://your-redis:6379/0 \
           -e CELERY_BROKER_URL=redis://your-redis:6379/0 \
           -e KANARI_API_KEY=sk_your_key \
           kanari-agent

Docker Compose

services:
  kanari:
    image: python:3.12-slim
    command: sh -c "pip install kanari && kanari agent"
    environment:
      REDIS_URL: redis://redis:6379/0
      CELERY_BROKER_URL: redis://redis:6379/0
      KANARI_API_KEY: sk_your_key
    depends_on:
      - redis
    restart: unless-stopped