> ## Documentation Index
> Fetch the complete documentation index at: https://getkanari.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Full reference for config file and environment variables

## Two config files, two purposes

| File | Purpose | Written by | Contains secrets? | Commit to git? |
| - | - | - | - | - |
| `kanari.yaml` | What to monitor — URLs, thresholds, queues | `kanari init` / you | No | ✅ Yes |
| `~/.kanari/config` | Who you are — API key and backend URL | `kanari login` | Yes | ❌ Never |

`kanari.yaml` lives next to your project code and is safe to version-control. `~/.kanari/config` lives in your home directory and is `chmod 600` — it holds your API key and should never be committed.

***

## Priority order

Configuration is loaded in this order (later overrides earlier):

1. Built-in defaults
2. `kanari.yaml` (or any file passed via `--config`)
3. `~/.kanari/config` (written by `kanari login`)
4. Environment variables

***

## Environment variables

| Variable | Description | Default |
| - | - | - |
| `REDIS_URL` | Redis connection URL | `redis://localhost:6379/0` |
| `CELERY_BROKER_URL` | Celery broker URL | `redis://localhost:6379/0` |
| `KANARI_API_KEY` | API key for getkanari.com (agent API mode) | — |
| `KANARI_API_URL` | Backend endpoint override | `https://api.getkanari.com` |
| `KANARI_LOCAL_MODE` | Set `true` to disable all API calls | `false` |
| `CHECK_INTERVAL` | Seconds between collection cycles (agent mode) | `30` |
| `KANARI_SANITIZE_TASK_SIGNATURES` | Set `false` to disable task name sanitization | `true` |
| `WORKER_OFFLINE_GRACE_SECONDS` | Seconds a worker-count drop must persist before raising `WORKERS_MISSING` | `90` |
| `WORKER_AUTO_RESOLVE_SECONDS` | Seconds after which the baseline resets automatically (`null` = alert indefinitely) | `null` |

***

## Config file reference

```yaml theme={null}
# ── Connections ────────────────────────────────────────────

# Redis URL. Supports redis://, rediss:// (TLS), redis+sentinel://
redis_url: redis://localhost:6379/0

# Celery broker URL. Usually the same as redis_url.
celery_broker_url: redis://localhost:6379/0

# The Celery app name. Used to initialize the Celery client.
celery_app_name: tasks

# ── Behavior ───────────────────────────────────────────────

# Seconds between collection cycles in agent mode.
check_interval_seconds: 30

# ── Queues ─────────────────────────────────────────────────

# Queues to monitor. Leave empty to auto-discover from workers.
# Auto-discovery uses `celery inspect active_queues`.
monitored_queues:
  - celery
  - default
  - emails
  - notifications

# ── Thresholds ─────────────────────────────────────────────

thresholds:
  # Triggers QUEUE_BACKLOG_* finding when depth exceeds this.
  max_queue_size: 1000

  # Triggers QUEUE_SLA_BREACH_* finding when oldest task
  # has been waiting longer than this (seconds).
  # Requires KanariStampPlugin for accurate measurement.
  max_wait_time_seconds: 60

  # Triggers STUCK_TASK finding when a task has been
  # executing for longer than this (seconds).
  max_task_runtime_seconds: 1800  # 30 minutes

  # Queues listed here get HIGH severity on QUEUE_BACKLOG
  # findings instead of MEDIUM. Use for business-critical queues.
  critical_queues:
    - emails
    - payments

  # Worker-offline detection (daemon only — `kanari run`).
  # Tracks a high-water baseline of alive workers. A sustained drop past the
  # grace period raises WORKERS_MISSING (CRITICAL). The backend maps this to
  # a pager alert when missing_workers > 0.
  #
  # Grace period: how long the count must stay low before alerting.
  worker_offline_grace_seconds: 90   # default: 90 s

  # Auto-resolve window: re-baseline after this many seconds of reduced count.
  # null (default) = fail loud — the alert persists until workers come back.
  # Set to e.g. 1800 for environments where intentional scale-down is common.
  worker_auto_resolve_seconds: null  # default: null (fail loud)

# ── Privacy ────────────────────────────────────────────────

privacy:
  # When true (default), task signatures are sanitized:
  # emails, UUIDs, and numeric IDs are replaced with placeholders.
  # Set false only if you're certain task names contain no PII.
  sanitize_task_signatures: true

# ── API (for kanari agent API mode) ──────────────────────

# Your getkanari.com API key. Can also be set via KANARI_API_KEY.
# api_key: sk_your_key_here

# Override the default API endpoint (advanced).
# api_url: https://api.getkanari.com

# Skip all API calls and only log locally.
# local_mode: false
```

***

## Common setups

### Minimal (env vars only)

```bash theme={null}
export REDIS_URL=redis://prod-redis:6379/0
export CELERY_BROKER_URL=redis://prod-redis:6379/0
kanari audit
```

### Auto-discovery with custom thresholds

```yaml theme={null}
# kanari.yaml — no monitored_queues means auto-discover from workers
redis_url: redis://prod-redis:6379/1
celery_broker_url: redis://prod-redis:6379/1
monitored_queues: []

thresholds:
  max_queue_size: 500
  max_wait_time_seconds: 30
  critical_queues:
    - payments
```

### Redis with password

```yaml theme={null}
redis_url: redis://:your-password@prod-redis:6379/0
celery_broker_url: redis://:your-password@prod-redis:6379/0
```

Kanari redacts passwords from all log output: `redis://***@prod-redis:6379/0`.

### Redis with TLS

```yaml theme={null}
redis_url: rediss://prod-redis:6380/0
celery_broker_url: rediss://prod-redis:6380/0
```

### Multiple environments via env vars

```bash theme={null}
# staging
REDIS_URL=redis://staging-redis:6379/0 kanari audit

# production
REDIS_URL=redis://prod-redis:6379/0 kanari audit --config prod.yaml
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.