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.