Dashboard Reports & Alerts Ops
Dashboard email reports (dashboard-report-subscriptions actions) and
analytics alert rules (analytics-alert-rules actions) are SQL-backed action
surfaces. This skill covers the deployment/runtime machinery behind them —
the agent chatting with an end user does not need this; it only needs the
action names and the user-facing constraints already in AGENTS.md.
Dashboard Email Report Rendering
- Scheduled reports render entirely server-side. They do not use a headless
browser, Chromium pack download, or the old
reportScreenshot=1 embed-session
screenshot URL; interactive dashboard screenshot capture remains separate.
- Each panel's query runs through the same source dispatcher the UI uses
(
runDashboardPanelQuery), inside the subscription owner's request
context, so per-source access scoping (BigQuery/Gong/HubSpot credentials,
org scoping) is preserved exactly as if the owner loaded the dashboard.
- Chart panels are drawn as SVG and rasterized to PNG with
@resvg/resvg-js,
then embedded in the email as cid: attachments. Fonts come from
resolveOgFontFiles() — resvg has no system fonts in a Lambda runtime,
so chart text silently renders blank (not an error) unless those bundled
font files are passed to it. Never drop that font wiring when touching
chart rendering.
- Non-chart panels (
section, metric, callout, table, heatmap) render
as real email HTML, not images. extension panels cannot be rendered for
email at all and instead link out to the live dashboard.
- A panel that fails to query renders a visible error card in its place and
marks the whole run
degraded; a degraded report is never sent or recorded
as if it were complete. If every panel fails, nothing is sent and the
subscription errors out instead of emailing an empty report.
- Subscriptions are capped at five distinct recipients
(
MAX_DASHBOARD_REPORT_RECIPIENTS) — recommend a mailing-list address for
larger audiences.
- The ten-minute retry delay is an eligibility floor, not a guarantee; the
*/15 sweep runs the retry on its first tick after that floor.
- The serverless delivery deadline (
SERVERLESS_REPORT_DELIVERY_BUDGET_MS in
server/jobs/dashboard-report.ts) reserves 220 seconds of the
dashboard-report-sweep-background function's 300-second netlify.toml
timeout for rendering and delivery, leaving the remainder for cleanup.
- Netlify processes one subscription per background invocation so every report
gets a fresh delivery deadline and first-party queries cannot contend with
another report. When due work remains, the worker queues another background
invocation immediately and drains the batch sequentially. Long-lived
(non-Netlify) runtimes default to a limit of 5, overridable with
DASHBOARD_REPORT_SWEEP_LIMIT.
Env Vars
DASHBOARD_REPORT_BASE_URL — overrides the dashboard link URL in emails; if
unset, falls back to getAppProductionUrl() (the APP_URL /
WORKSPACE_OAUTH_ORIGIN / BETTER_AUTH_URL chain).
RESEND_API_KEY or SENDGRID_API_KEY plus EMAIL_FROM — required to send
the report email at all.
DASHBOARD_REPORTS_CRON_SECRET — bearer token external cron callers must
send to POST /api/dashboard-reports/run.
DASHBOARD_REPORT_SWEEP_LIMIT — overrides the per-tick sweep size on
non-Netlify runtimes (see above).
Cron Wiring
- Netlify builds emit a scheduled trigger plus a background worker from
scripts/emit-netlify-dashboard-report-cron.ts, using a per-deploy internal
token and disabling the in-process interval scheduler on Netlify to avoid
duplicate sends.
- External cron callers can sweep due reports by POSTing
/api/dashboard-reports/run with
Authorization: Bearer $DASHBOARD_REPORTS_CRON_SECRET.
- The same
scripts/emit-netlify-dashboard-report-cron.ts script also emits
the alert-rule cron trigger plus background worker, running every five
minutes on Netlify. Long-lived runtimes use the in-process scheduler unless
ANALYTICS_ALERT_JOBS=0 is set.
- External cron callers can run due alerts by POSTing
/api/analytics-alerts/run with
Authorization: Bearer $ANALYTICS_ALERTS_CRON_SECRET.
Alert Notification Delivery
Alert notifications use the shared notification channel registry
(channels can include inbox, email, slack, webhook, or any custom
registered channel):
- Slack/webhook delivery prefers per-rule
metadata.delivery.slackWebhookUrl
/ metadata.delivery.webhookUrl (uptime monitors store these on the
monitor row), then falls back to NOTIFICATIONS_SLACK_WEBHOOK_URL /
NOTIFICATIONS_WEBHOOK_URL. Optional NOTIFICATIONS_SLACK_WEBHOOK_AUTH
configures Slack auth.
- Email delivery needs
RESEND_API_KEY or SENDGRID_API_KEY plus
EMAIL_FROM. Per-rule emailRecipients fall back to
NOTIFICATIONS_EMAIL_RECIPIENTS. Saving explicit emailRecipients also
remembers them as the current user's defaults for the next alert rule
created in Settings.
Users can also view and manage report subscriptions and alert rules in
Settings; that UI uses the same action surface as the agent, so no separate
implementation is needed there. Alert rules are the Alerts tab on
Analytics › General (buildSettingsRoute("app", "alerts")), and the per-user
"Email new error alerts" and "Bell sound" switches are on Analytics ›
Notifications (buildSettingsRoute("notifications")). The agent changes those
two with update-analytics-notification-preferences.
Related Skills
- dashboard-management — the dashboard artifact model these features
attach to.
- integration-webhooks (root) — the general queue-and-processor pattern
for outbound webhook delivery.
1---2name: dashboard-ops3description: >-4 Deployment and runtime internals for dashboard email reports and analytics5 alert rules: server-side SVG/PNG report rendering, serverless timing6 budgets, cron wiring, and notification delivery env vars. Use when7 configuring, deploying, or debugging report/alert delivery infrastructure —8 not when just creating a report subscription or alert rule via the action9 surface.10scope: dev11metadata:12 source: https://skillmd.com/skills/builderio/dashboard-ops13---1415# Dashboard Reports & Alerts Ops1617Dashboard email reports (`dashboard-report-subscriptions` actions) and18analytics alert rules (`analytics-alert-rules` actions) are SQL-backed action19surfaces. This skill covers the deployment/runtime machinery behind them —20the agent chatting with an end user does not need this; it only needs the21action names and the user-facing constraints already in `AGENTS.md`.2223## Dashboard Email Report Rendering2425- Scheduled reports render entirely server-side. They do not use a headless26 browser, Chromium pack download, or the old `reportScreenshot=1` embed-session27 screenshot URL; interactive dashboard screenshot capture remains separate.28- Each panel's query runs through the same source dispatcher the UI uses29 (`runDashboardPanelQuery`), inside the subscription owner's request30 context, so per-source access scoping (BigQuery/Gong/HubSpot credentials,31 org scoping) is preserved exactly as if the owner loaded the dashboard.32- Chart panels are drawn as SVG and rasterized to PNG with `@resvg/resvg-js`,33 then embedded in the email as `cid:` attachments. Fonts come from34 `resolveOgFontFiles()` — **resvg has no system fonts in a Lambda runtime,35 so chart text silently renders blank (not an error) unless those bundled36 font files are passed to it.** Never drop that font wiring when touching37 chart rendering.38- Non-chart panels (`section`, `metric`, `callout`, `table`, `heatmap`) render39 as real email HTML, not images. `extension` panels cannot be rendered for40 email at all and instead link out to the live dashboard.41- A panel that fails to query renders a visible error card in its place and42 marks the whole run `degraded`; a degraded report is never sent or recorded43 as if it were complete. If every panel fails, nothing is sent and the44 subscription errors out instead of emailing an empty report.45- Subscriptions are capped at five distinct recipients46 (`MAX_DASHBOARD_REPORT_RECIPIENTS`) — recommend a mailing-list address for47 larger audiences.48- The ten-minute retry delay is an eligibility floor, not a guarantee; the49 `*/15` sweep runs the retry on its first tick after that floor.50- The serverless delivery deadline (`SERVERLESS_REPORT_DELIVERY_BUDGET_MS` in51 `server/jobs/dashboard-report.ts`) reserves 220 seconds of the52 `dashboard-report-sweep-background` function's 300-second `netlify.toml`53 timeout for rendering and delivery, leaving the remainder for cleanup.54- Netlify processes one subscription per background invocation so every report55 gets a fresh delivery deadline and first-party queries cannot contend with56 another report. When due work remains, the worker queues another background57 invocation immediately and drains the batch sequentially. Long-lived58 (non-Netlify) runtimes default to a limit of 5, overridable with59 `DASHBOARD_REPORT_SWEEP_LIMIT`.6061### Env Vars6263- `DASHBOARD_REPORT_BASE_URL` — overrides the dashboard link URL in emails; if64 unset, falls back to `getAppProductionUrl()` (the `APP_URL` /65 `WORKSPACE_OAUTH_ORIGIN` / `BETTER_AUTH_URL` chain).66- `RESEND_API_KEY` or `SENDGRID_API_KEY` plus `EMAIL_FROM` — required to send67 the report email at all.68- `DASHBOARD_REPORTS_CRON_SECRET` — bearer token external cron callers must69 send to `POST /api/dashboard-reports/run`.70- `DASHBOARD_REPORT_SWEEP_LIMIT` — overrides the per-tick sweep size on71 non-Netlify runtimes (see above).7273## Cron Wiring7475- Netlify builds emit a scheduled trigger plus a background worker from76 `scripts/emit-netlify-dashboard-report-cron.ts`, using a per-deploy internal77 token and disabling the in-process interval scheduler on Netlify to avoid78 duplicate sends.79- External cron callers can sweep due reports by POSTing80 `/api/dashboard-reports/run` with81 `Authorization: Bearer $DASHBOARD_REPORTS_CRON_SECRET`.82- The same `scripts/emit-netlify-dashboard-report-cron.ts` script also emits83 the alert-rule cron trigger plus background worker, running every five84 minutes on Netlify. Long-lived runtimes use the in-process scheduler unless85 `ANALYTICS_ALERT_JOBS=0` is set.86- External cron callers can run due alerts by POSTing87 `/api/analytics-alerts/run` with88 `Authorization: Bearer $ANALYTICS_ALERTS_CRON_SECRET`.8990## Alert Notification Delivery9192Alert notifications use the shared notification channel registry93(`channels` can include `inbox`, `email`, `slack`, `webhook`, or any custom94registered channel):9596- Slack/webhook delivery prefers per-rule `metadata.delivery.slackWebhookUrl`97 / `metadata.delivery.webhookUrl` (uptime monitors store these on the98 monitor row), then falls back to `NOTIFICATIONS_SLACK_WEBHOOK_URL` /99 `NOTIFICATIONS_WEBHOOK_URL`. Optional `NOTIFICATIONS_SLACK_WEBHOOK_AUTH`100 configures Slack auth.101- Email delivery needs `RESEND_API_KEY` or `SENDGRID_API_KEY` plus102 `EMAIL_FROM`. Per-rule `emailRecipients` fall back to103 `NOTIFICATIONS_EMAIL_RECIPIENTS`. Saving explicit `emailRecipients` also104 remembers them as the current user's defaults for the next alert rule105 created in Settings.106107Users can also view and manage report subscriptions and alert rules in108Settings; that UI uses the same action surface as the agent, so no separate109implementation is needed there. Alert rules are the Alerts tab on110Analytics › General (`buildSettingsRoute("app", "alerts")`), and the per-user111"Email new error alerts" and "Bell sound" switches are on Analytics ›112Notifications (`buildSettingsRoute("notifications")`). The agent changes those113two with `update-analytics-notification-preferences`.114115## Related Skills116117- **dashboard-management** — the dashboard artifact model these features118 attach to.119- **integration-webhooks** (root) — the general queue-and-processor pattern120 for outbound webhook delivery.