Notification Diagnostics
Summary
The service exposes an unusually rich diagnostic surface for its size: a stage-by-stage audit trail, per-attempt delivery records, an idempotency lookup, aggregate counts and two test hooks.
Audience
DevOps engineers, engineers, support, QA and architects.
Reference Content
The verified reference material for this topic is set out in the sections below.
Diagnostic surfaces
| Surface | Answers |
|---|---|
| Audit trail | What happened to this event or message, stage by stage |
| Delivery attempts | How many times we tried, against which provider, how long each took and why each failed |
| Idempotency lookup | Was this event already processed, and with what outcome |
| Failed queue | Which messages exhausted their retries |
| Single message read | What is the current state of this message |
| Statistics | Platform-wide counts across templates, recipients, messages and events |
| Service information | Which service and environment is responding |
The audit trail as the primary tool
The audit trail records thirteen stages and is queryable by event, correlation identifier or message identifier. It is the only surface that explains why a notification did not arrive, because it records the negative outcomes explicitly: duplicate, stale, template missing, suppressed and delivery failed.
Each row carries a correlation identifier and, when tracing is active, a trace identifier — so an audit row can be joined to a distributed trace.
One verified caveat. Audit rows persist the raw correlation field rather than the envelope's effective fallback. An event published without a correlation identifier is stored with a null correlation and cannot be found through the correlation filter; it must be located by event identifier instead.
Attempt records
Every delivery attempt writes a row carrying attempt number, channel, provider, outcome, error text and both timestamps plus a measured duration. Error text is truncated in application code before storage, so an oversized provider error is stored clipped rather than rejected.
This is the most precise diagnostic data the service holds, and it is reachable only per message.
Test hooks
Two endpoints exist for verification: one dispatches an event straight through the pipeline without a broker, and one publishes onto the broker so the consumer round-trips it. Both accept a forced-failure flag honoured by every channel sender, which makes the failure and retry paths reproducible on demand.
Operational caution. Both are mapped unconditionally with no environment guard and no authorization. On a reachable instance they will inject real events into the pipeline and publish onto the shared platform exchange. They are diagnostic affordances, not safe production tools.
Diagnostic gaps
| Question | Answerable |
|---|---|
| Why did this notification not arrive | Yes — audit trail |
| How many times did we try and why did it fail | Yes — attempts |
| Is the consumer connected to the broker | No — logs only |
| How deep is the queue | No |
| Which tenant do these failures belong to | No — no tenant filter on the failed or audit reads |
| How many failures in the last hour | No — no time filter or aggregation |
| Which channel fails most | No — no per-channel aggregation |
Classification
Implemented.
Requires confirmation
Whether the test hooks should be environment-guarded requires confirmation.
Related Articles
See Also
Keywords
- Notification database
- Diagnostics
- Draft database documentation
Source References
microservices/src/notification-service/Api/NotificationEndpoints.csmicroservices/src/notification-service/Application/NotificationDispatcher.csmicroservices/src/notification-service/Application/NotificationTelemetry.csmicroservices/src/notification-service/Messaging/NotificationEventConsumer.cs
Revision Information
- Status: Draft
- Last reviewed: 2026-07-21
- Review cycle: Quarterly