@@ -166,22 +166,22 @@ to manage these values.
166166## Dashboard Provisioning
167167
168168HyperDX supports file-based dashboard provisioning, similar to Grafana's
169- provisioning system. A scheduled task reads ` .json` files from a directory
170- and upserts dashboards into MongoDB, matched by name for idempotency.
171- The task runs on the same schedule as other HyperDX tasks (every minute
172- when using the built-in scheduler, or on your own schedule when running
173- tasks externally).
169+ provisioning system. A scheduled task reads ` .json` files from a directory and
170+ upserts dashboards into MongoDB, matched by name for idempotency. The task runs
171+ on the same schedule as other HyperDX tasks (every minute when using the
172+ built-in scheduler, or on your own schedule when running tasks externally).
174173
175174# ## Environment Variables
176175
177- | Variable | Required | Default | Description |
178- | ----------------------------------- | -------- | ------- | ------------- -------------------------------------------------- |
179- | `DASHBOARD_PROVISIONER_DIR` | Yes | | Directory to watch for `.json` dashboard files |
180- | `DASHBOARD_PROVISIONER_TEAM_ID` | No\* | | Scope provisioning to a specific team ID |
181- | `DASHBOARD_PROVISIONER_ALL_TEAMS` | No\* | `false` | Set to `true` to provision dashboards to all teams |
176+ | Variable | Required | Default | Description |
177+ | --------------------------------- | -------- | ------- | -------------------------------------------------- |
178+ | `DASHBOARD_PROVISIONER_DIR` | Yes | | Directory to watch for `.json` dashboard files |
179+ | `DASHBOARD_PROVISIONER_TEAM_ID` | No\* | | Scope provisioning to a specific team ID |
180+ | `DASHBOARD_PROVISIONER_ALL_TEAMS` | No\* | `false` | Set to `true` to provision dashboards to all teams |
182181
183- \*One of `DASHBOARD_PROVISIONER_TEAM_ID` or `DASHBOARD_PROVISIONER_ALL_TEAMS=true`
184- is required when `DASHBOARD_PROVISIONER_DIR` is set.
182+ \*One of `DASHBOARD_PROVISIONER_TEAM_ID` or
183+ ` DASHBOARD_PROVISIONER_ALL_TEAMS=true` is required when
184+ ` DASHBOARD_PROVISIONER_DIR` is set.
185185
186186# ## Dashboard JSON Format
187187
@@ -234,9 +234,18 @@ API accepts. The provisioner creates or updates that tile alert on every sync:
234234 "h": 4,
235235 "config": {
236236 "name": "Error rate",
237- "source": "Logs ",
237+ "source": "<source ObjectId> ",
238238 "displayType": "line",
239- "select": [{ "aggFn": "count", "where": "SeverityText:error" }],
239+ "select": [
240+ {
241+ "aggFn": "count",
242+ "aggCondition": "SeverityText:error",
243+ "aggConditionLanguage": "lucene",
244+ "valueExpression": ""
245+ }
246+ ],
247+ "where": "",
248+ "whereLanguage": "lucene",
240249 "alert": {
241250 "interval": "5m",
242251 "threshold": 100,
@@ -247,23 +256,32 @@ API accepts. The provisioner creates or updates that tile alert on every sync:
247256}
248257` ` `
249258
250- - A channel names its webhook with `webhookName`, which is looked up among the
251- team's webhooks on every sync, so the same file works across installs and,
252- with `DASHBOARD_PROVISIONER_ALL_TEAMS=true`, across teams that each have a
253- webhook of that name. `webhookId` still works too. A name that matches no
254- webhook, or webhooks of more than one service, fails validation
259+ - Each alert gets the checks the alerts API applies, plus the ones the alert
260+ task needs to evaluate it : a Line, Stacked Bar or Number display type, no
261+ PromQL, a valid raw SQL alert query, and a source, connection and webhooks
262+ that exist in the team. `source` is the source's ObjectId, so with
263+ ` DASHBOARD_PROVISIONER_ALL_TEAMS=true` an alert is only created in the team
264+ that owns its source
265+ - A channel can name its webhook with `webhookName`, looked up among the team's
266+ webhooks on every sync, instead of a `webhookId` that only exists in one
267+ install. A name that matches no webhook, or more than one, fails validation
255268- Provisioned alerts are flagged with `provisioned : true`. Removing an alert
256- from its tile, or the tile from the file, deletes it on the next sync
269+ from its tile, or the tile from the file, deletes it on the next sync. Keep
270+ tile ids stable : changing one replaces the alert and loses its history
257271- Removing a dashboard's file, or renaming the dashboard, deletes the
258272 provisioned alerts of the dashboard it leaves behind. The dashboard itself is
259273 kept, as above. This cleanup only runs when every file in the directory was
260- read and validated, and never when the directory has no valid files, so a
261- broken file or an empty mount does not remove alerts
262- - An alert that fails validation (for example an unknown webhook, or a raw SQL
263- tile whose display type or query does not support alerts) is skipped with a
264- warning and keeps its last valid version
265- - Alerts created in the app on a provisioned dashboard are left alone, unless
266- the file declares an alert on the same tile, which then replaces it
274+ read, validated and synced, and never when the directory has no valid files,
275+ so a broken file, a failed sync or an empty mount does not remove alerts
276+ - An alert that fails validation is skipped with a warning. Its tile keeps the
277+ version from the last sync, query and alert together, so an old alert never
278+ evaluates a new query; a new tile is added without its alert
279+ - Alerts created in the app are never changed or deleted. A file that declares
280+ an alert on a tile that already has one from the app is skipped with a warning
281+ - Like the dashboard, a provisioned alert edited or deleted in the app is
282+ restored from its file on the next sync
283+ - Files that share a dashboard name are skipped with a warning, except the first
284+ in file name order
267285
268286# # Note on Security
269287
0 commit comments