Observability
What telemetry exists, how to follow one action across it — and, more usefully, what is not there, so you stop looking for it.
Correlation id — useful, but less than you would hope
Every request is stamped with an X-Correlation-Id, generated if the caller did not supply one, and
returned on the response header. An integrator can supply their own, which lets them tie their logs to a
Commerce request — worth asking any upstream team to do, since it costs them a header.
Warning
You cannot search the application log by correlation id. The middleware stores it on the request and echoes it on the response; it does not add it to a log scope, so ordinary log entries do not carry it. Exactly one place logs it — an unhandled exception on the public API.
It is also not stamped onto queued work, so it does not follow background processing. An order's ERP post cannot be traced back to the request that created it this way.
See Logging.
So in practice:
| Worth having | It ties an integrator's own logs to a Commerce request, and it identifies a specific public-API failure |
| Do not rely on it | For following one action through the platform. Use customer number, order number and a time window instead — and narrow by time first |
Application Insights
Telemetry goes to Application Insights. Two things to understand before you rely on it.
It is attached by the platform, not built into the application. The connection string is injected as an app setting by the infrastructure, and there is no telemetry SDK in the Commerce codebase. What you get is what the platform agent collects.
| Reliably present | Do not assume |
|---|---|
| Requests — path, status, duration | Custom events or metrics. Nothing emits them |
| Dependencies — SQL, outbound HTTP | Structured properties on log entries |
| Unhandled exceptions with stack traces | Application log lines at every level |
| Performance counters | Business-level telemetry such as orders placed |
Important
Verify in the portal whether application log traces are present in your environment, rather than
assuming either way. Because instrumentation is agent-attached rather than configured in code,
whether ILogger output reaches Application Insights depends on the platform configuration, not on
anything in this repository. Establish it once for your environment and write down the answer.
What is genuinely reliable is the request and dependency view — and it answers most of the "slow or erroring" questions on its own. A failing dependency to the ERP, the identity provider or the search service shows up there clearly, and it distinguishes our fault from theirs faster than reading logs.
Application logs
Logging is standard framework logging at Information, with framework noise at Warning. There is no
structured logging library and no custom sink.
In practice: log output goes to the platform's log stream and is visible through the app service's own diagnostics.
Health
There is a /health endpoint, unauthenticated, which returns a static healthy response.
Warning
It proves the process is running and nothing more. It does not check the database, the ERP, the identity provider or the queue. A healthy response alongside a broken site is entirely possible and is not a contradiction.
It exists as the conventional name for future probes. Do not use it to conclude the platform is fine.
What is not there
Stating the gaps plainly, because looking for something that does not exist is the most expensive way to spend an incident.
| Alerting | Nothing in this repository configures an alert. You will learn about a problem from a person |
| A dashboard | No pre-built view. Application Insights is queried ad hoc |
| Business metrics | Orders placed, checkout failures, search volumes — none are emitted as telemetry |
| Distributed tracing across systems | The correlation id is ours. It does not follow work into the ERP or the payment provider |
| Audit of who did what in the back office | Records carry created and modified timestamps, but there is no administrative action log |
| Error grouping by customer | Telemetry is not tagged with a customer, so you cannot slice failures by one |
Practical order of investigation
For "the site is slow or erroring", in this order:
- Request telemetry — is it one endpoint or all of them? One status code or many? Started when?
- Dependency telemetry — is a downstream system slow or failing? That reframes the whole ticket
- Exceptions — a spike with a stack trace usually names the cause outright
- Deployment timing — did it start at a deployment? Migrations run before the new code, so a deployment window is a genuine suspect. See CI/CD
- The queue — if the symptom is "things are not happening" rather than "requests are failing", it is async work, not the web tier