|
| 1 | +--- |
| 2 | +title: Alerts & Webhooks |
| 3 | +--- |
| 4 | + |
| 5 | +# Alerts & Webhooks |
| 6 | + |
| 7 | +<Badge type="tip" text="New in v10" /> |
| 8 | + |
| 9 | +Dozzle v10 introduces a powerful alerting system that lets you monitor container logs and receive notifications when specific conditions are met. Alerts use customizable expressions to filter containers and log messages, and can send notifications to webhooks, Slack, Discord, ntfy, or [Dozzle Cloud](/guide/dozzle-cloud). |
| 10 | + |
| 11 | +## How It Works |
| 12 | + |
| 13 | +Alerts are configured with two expressions: |
| 14 | + |
| 15 | +1. **Container filter** — selects which containers to monitor |
| 16 | +2. **Log filter** — defines which log messages trigger the alert |
| 17 | + |
| 18 | +When a log entry matches both filters, Dozzle sends a notification to the configured destination. |
| 19 | + |
| 20 | +> [!IMPORTANT] |
| 21 | +> Alert and destination configurations are stored in the `/data` directory. You must mount this directory as a volume to persist your notification settings across container restarts. |
| 22 | +
|
| 23 | +::: code-group |
| 24 | + |
| 25 | +```sh |
| 26 | +docker run -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/data:/data -p 8080:8080 amir20/dozzle:latest |
| 27 | +``` |
| 28 | + |
| 29 | +```yaml [docker-compose.yml] |
| 30 | +services: |
| 31 | + dozzle: |
| 32 | + image: amir20/dozzle:latest |
| 33 | + volumes: |
| 34 | + - /var/run/docker.sock:/var/run/docker.sock |
| 35 | + - /path/to/data:/data |
| 36 | + ports: |
| 37 | + - 8080:8080 |
| 38 | +``` |
| 39 | +
|
| 40 | +::: |
| 41 | +
|
| 42 | +## Setting Up a Destination |
| 43 | +
|
| 44 | +Before creating alerts, you need to configure at least one notification destination. Navigate to the **Notifications** page in Dozzle and click **Add Destination**. |
| 45 | +
|
| 46 | +### Webhook |
| 47 | +
|
| 48 | +Webhooks send an HTTP POST request to a URL of your choice. Dozzle includes built-in payload templates for popular services: |
| 49 | +
|
| 50 | +- **Slack** — formatted with blocks and markdown |
| 51 | +- **Discord** — formatted for Discord webhook API |
| 52 | +- **ntfy** — formatted for [ntfy.sh](https://ntfy.sh) push notifications |
| 53 | +- **Custom** — generic JSON payload you can customize |
| 54 | +
|
| 55 | +You can also write your own payload template using Go's `text/template` syntax. The following variables are available: |
| 56 | + |
| 57 | +<div v-pre> |
| 58 | + |
| 59 | +| Variable | Description | |
| 60 | +| ------------------------- | --------------------------- | |
| 61 | +| `{{.Container.Name}}` | Container name | |
| 62 | +| `{{.Container.Image}}` | Container image | |
| 63 | +| `{{.Container.HostName}}` | Docker host name | |
| 64 | +| `{{.Container.State}}` | Container state | |
| 65 | +| `{{.Log.Message}}` | Log message content | |
| 66 | +| `{{.Log.Level}}` | Log level | |
| 67 | +| `{{.Log.Timestamp}}` | Log timestamp | |
| 68 | +| `{{.Log.Stream}}` | Stream type (stdout/stderr) | |
| 69 | +| `{{.Subscription.Name}}` | Alert rule name | |
| 70 | + |
| 71 | +</div> |
| 72 | + |
| 73 | +> [!TIP] |
| 74 | +> Use the **Test** button to verify your webhook is working before saving. |
| 75 | + |
| 76 | +### Dozzle Cloud |
| 77 | + |
| 78 | +You can also send alerts to [Dozzle Cloud](/guide/dozzle-cloud) for centralized monitoring across multiple Dozzle instances. See the [Dozzle Cloud guide](/guide/dozzle-cloud) for more details. |
| 79 | + |
| 80 | +## Creating an Alert |
| 81 | + |
| 82 | +Navigate to the **Notifications** page and click **Add Alert**. You'll need to configure: |
| 83 | + |
| 84 | +### Container Expression |
| 85 | + |
| 86 | +The container expression selects which containers to monitor. Available properties: |
| 87 | + |
| 88 | +| Property | Type | Example | |
| 89 | +| ---------- | ------ | ------------------------------- | |
| 90 | +| `name` | string | `name contains "api"` | |
| 91 | +| `image` | string | `image == "nginx:latest"` | |
| 92 | +| `state` | string | `state == "running"` | |
| 93 | +| `health` | string | `health == "unhealthy"` | |
| 94 | +| `hostName` | string | `hostName == "prod-host"` | |
| 95 | +| `labels` | map | `labels["env"] == "production"` | |
| 96 | + |
| 97 | +You can combine conditions with `&&` (AND), `||` (OR), and `!` (NOT): |
| 98 | + |
| 99 | +``` |
| 100 | +name contains "api" && labels["env"] == "production" |
| 101 | +``` |
| 102 | + |
| 103 | +### Log Expression |
| 104 | + |
| 105 | +The log expression filters which log messages trigger the alert. Available properties: |
| 106 | + |
| 107 | +| Property | Type | Example | |
| 108 | +| --------- | ---------- | -------------------------- | |
| 109 | +| `message` | string/map | `message contains "error"` | |
| 110 | +| `level` | string | `level == "error"` | |
| 111 | +| `stream` | string | `stream == "stderr"` | |
| 112 | +| `type` | string | `type == "complex"` | |
| 113 | + |
| 114 | +For JSON logs, you can access nested fields using dot notation: |
| 115 | + |
| 116 | +``` |
| 117 | +message.status >= 500 && message.path contains "/api" |
| 118 | +``` |
| 119 | + |
| 120 | +Supported string operators include `contains`, `startsWith`, `endsWith`, and `matches` (regex). |
| 121 | + |
| 122 | +### Examples |
| 123 | + |
| 124 | +**Alert on all errors from production containers:** |
| 125 | + |
| 126 | +``` |
| 127 | +Container: labels["env"] == "production" |
| 128 | +Log: level == "error" |
| 129 | +``` |
| 130 | +
|
| 131 | +**Alert on HTTP 5xx errors from API containers:** |
| 132 | +
|
| 133 | +``` |
| 134 | +Container: name contains "api" |
| 135 | +Log: message.status >= 500 |
| 136 | +``` |
| 137 | +
|
| 138 | +**Alert on any stderr output from a specific image:** |
| 139 | +
|
| 140 | +``` |
| 141 | +Container: image startsWith "myapp/" |
| 142 | +Log: stream == "stderr" |
| 143 | +``` |
| 144 | +
|
| 145 | +> [!NOTE] |
| 146 | +> The alert editor includes autocomplete and real-time validation. You can preview matched containers and logs before saving. |
| 147 | +
|
| 148 | +## Managing Alerts |
| 149 | +
|
| 150 | +From the Notifications page, you can: |
| 151 | +
|
| 152 | +- **Enable/disable** alerts without deleting them |
| 153 | +- **Edit** alert expressions and destinations |
| 154 | +- **View statistics** including trigger count, matched containers, and last triggered time |
| 155 | +- **Delete** alerts that are no longer needed |
0 commit comments