Observability
Notifizz emits enough signal to follow any single delivery from event acceptance to bell update — the trick is knowing where to look. This page covers the customer-side observability surface: correlation IDs, the dashboard’s tracing views, AI usage observability.TL;DR
- Correlation ID stamped at message creation time — propagates through every queue hop and inbox write.
- Per-workflow-instance trace in the dashboard — every step (orchestrator, enricher, channel) with timing.
- AI usage observability — see which campaign / user consumed how many AI credits.
- Dev tasks — proactive surfacing of orchestrator issues before they hit prod.
Correlation IDs
Every notification carries a correlation id stamped at message creation time. The id propagates through:- The workflow instance that created it.
- Every queue hop (the internal queue stages).
- The delivery record document.
- The widget delivery (visible in the message detail).
- Find the correlation id in the dashboard delivery history (per-message detail view).
- Search backend logs for the id — every log line touched by the delivery includes it.
- Cross-reference with the workflow trace view in the dashboard.
Workflow trace
Every workflow instance gets a trace view in the dashboard:- Steps in execution order — initial event match, orchestrator code, enricher calls, channel dispatch.
- Timing per step — useful to spot the slow link (usually a cold enricher or a slow channel render).
- Inputs and outputs at each boundary — the orchestrator’s recipient list, the enricher’s params and response, the rendered template.
- Errors with stack traces (for orchestrator code) or typed error codes (for enrichers, channels).
Dev tasks
Dev tasks are proactive — the dashboard surfaces orchestrator issues at edit time, before they hit traffic:| Dev task | Trigger |
|---|---|
| Missing event property | Orchestrator reads event.properties.foo but no event you’ve sent has that key. |
| Undefined enricher | Orchestrator calls enrichWith("notARegisteredEnricher", ...). |
| Empty recipient list | Orchestrator returns [] for typical inputs. |
| Type mismatch | The orchestrator’s typed signature contradicts the event’s actual shape. |
AI usage observability
The AI authoring layer (orchestrator codegen, dev-task auto-resolution) consumes credits. The dashboard shows:- Per-user usage — how many credits each team member consumed.
- Per-campaign usage — which campaigns required the most AI work to author.
- Per-action breakdown — codegen vs review vs dev-task resolution.
”My event didn’t fire” — checklist
| Check | Where to look |
|---|---|
| Did the SDK call succeed (no 4xx/5xx)? | Your application logs. |
| Did the backend accept the event? | Dashboard → Events → recent events for the environment. |
| Was a campaign matched? | Dashboard → Delivery History → filter by event name. No entries means no campaign listened. |
| Was the campaign in a runnable status? | Campaign detail → status. Editing only fires on dev (and even then may not dispatch); Live fires everywhere. |
| Did the orchestrator run? | Workflow instance trace — if absent, the campaign was filtered out (status, env mismatch). |
| Did the orchestrator return recipients? | Trace step “build recipients” — empty means no message gets created. |
| Did the channel dispatch? | Trace step “send” — failures show the typed error. |
”My campaign didn’t run” — same checklist, deeper
If the workflow instance was created but no notification reached the user:- Recipient resolution — orchestrator returned empty list, or returned a recipient with missing
email. - Channel config — the campaign references an NC config that no longer exists, or an email config without verified sending domain.
- Variable rendering — the template references a variable that didn’t resolve.
- Provider-side rejection — for email, the provider may reject deliverability (bounce, complaint history).
”My enricher times out” — what next?
In the workflow trace, locate the enricher step. Three signals:| Signal | Likely cause | Fix |
|---|---|---|
| Step timed out after 10–15s | Slow handler or unreachable URL | Cache aggressively (cache: { ttl: "1h" }); confirm the URL is reachable from the Notifizz region. |
EnricherHmacVerificationError: bad-signature | Secret mismatch | Re-copy webhookSigningSecret from the dashboard. |
EnricherInputValidationError | Schema mismatch | The orchestrator passes params your input schema rejects. Update one to match. |
FAQ
Event tracked but no campaign — what do I check first?
Event tracked but no campaign — what do I check first?
The Events catalog (Dashboard → Events). If your event is missing, the SDK secret you used didn’t resolve to this environment. If your event is there, the campaign side is the issue — most likely no campaign is wired to the exact event name (typo, casing, environment mismatch).
Campaign ran but no message — where do I look?
Campaign ran but no message — where do I look?
Workflow instance trace. The orchestrator returns a recipient list; if empty, no messages get created. If the orchestrator branches on a property, verify that property reached it (the trace shows inputs).
Correlation ID for one delivery?
Correlation ID for one delivery?
Per-message detail view in delivery history. The id is in the metadata block; click to copy. Use it as a search term across your application logs and the workflow trace.
Enricher took 12 seconds — find which one?
Enricher took 12 seconds — find which one?
The workflow trace lists per-step timings. The slow step is usually the cold cache miss on a per-call enricher; check the cache policy on the enricher’s registration and consider raising the TTL.
AI usage spiked — see who used what?
AI usage spiked — see who used what?
Dashboard → Settings → AI Usage. The per-user breakdown shows credits by team member; per-campaign shows which campaigns drove the spike. Most spikes trace to a single dev iterating on a complex orchestrator — pair-review can shorten the loop.
Logs show my event but no `correlationId` field — why?
Logs show my event but no `correlationId` field — why?
The id is stamped at message creation time, not at event acceptance. If the campaign matched and a message was created, the id is in the workflow instance and the delivery record. If no message was ever created (orchestrator returned empty recipients), there’s no message-level id — use the workflow instance id instead.
See also
Delivery history & stats
Aggregated funnel view, per-campaign metrics.
Troubleshooting
Symptom → cause → fix tables.
Activity log
Team-side audit trail of campaign edits.
Error catalogue
Every typed error code.