Learn / .NET API Engineering Path
Observability, Deploys, and Incident Runbooks
Connect logs, health, metrics, release checks, and rollback decisions into an operations playbook a teammate can execute.
Course: .NET API Engineering Path. Level: Advanced. Topic: Typed backend.
Stage: pro - Pro operations - Observability, deploys, and incident response. Connect runtime signals to deploy and incident decisions so another engineer can operate the API.
Outcomes
- Emit structured logs with correlation fields.
- Define deploy and rollback signals.
- Write an incident note tied to health and query evidence.
Concepts
- structured logging
- correlation id
- rollback signal
- incident runbook
Concept flow
Show how observability, deploys, and incident response moves from trigger to implementation outcome in .NET APIs.
- Request
- Correlation ID
- Structured log
- Metric
- Health endpoint
- Runbook
Session flow
- Model structured logging (concept, 12 min) — Name the decisions behind structured logging before writing code.
- Emit structured logs with correlation fields.
- Explain where structured logging belongs in order management API.
- Build the vertical slice (walkthrough, 21 min) — Implement the smallest useful slice in Orders/RequestLogging.cs.
- Define deploy and rollback signals.
- Connect correlation id to a working example.
- Verify and harden (exercise, 14 min) — Write a short incident review using a health check and log excerpt.
- Write an incident note tied to health and query evidence.
- Record one risk or follow-up before moving on.
Code example
C# in Orders/RequestLogging.cs.
app.Use(async (context, next) =>
{
var correlationId = context.TraceIdentifier;
using var scope = logger.BeginScope(new Dictionary<string, object>
{
["correlationId"] = correlationId,
["route"] = context.Request.Path.Value ?? "unknown"
});
await next();
});
Walkthrough examples
- Observability, Deploys, and Incident Runbooks in a order management API — A team is extending a production-grade ASP.NET Core order API and needs this lesson's pattern to be clear enough for review, testing, and future maintenance.
- File: Orders/RequestLogging.cs
- File: src/Orders.Application/observability-deploy-and-incident-runbooks.cs
- File: tests/Orders.Api.Tests/observability-deploy-and-incident-runbooks.Tests.cs
- File: docs/dotnet-advanced/observability-deploy-and-incident-runbooks.md
- Start from the provided C# snippet and make the intent visible in names and boundaries.
- Apply the checklist item "Logs include correlation context" before adding extra behavior.
- Write down how the implementation changes when correlation id fails or becomes slow.
Practice
- Add correlation fields to one request log.
- Define three rollback signals for the order API.
- Write a short incident review using a health check and log excerpt.
Checklist
- Logs include correlation context
- Deploy checklist names smoke tests
- Rollback signals are measurable
- Incident note links symptoms to evidence
Quiz prompts
- Which artifact best proves a pro-grade deploy is ready to keep receiving traffic? — Pro operations require evidence that another engineer can verify during deploy or incident response.
- A teammate wants to hide structured logging inside a convenient helper. What should you check first? — Place structured logging at the boundary that keeps order management API behavior explicit, testable, and reviewable.
- Which artifact best proves this .NET APIs lesson is ready for review? — Production-ready learning needs evidence: a test, trace, command, screenshot, or log that catches the risk again.
- Pro operations: a teammate says the happy path works, but "Correlated structured logs" is still implicit. What should you ask for before merging? — Correlated structured logs belongs in the pro stage only when the decision is visible, testable, and tied to a realistic failure mode.
- A reviewer has five minutes to evaluate this pro .NET APIs slice. Which evidence is strongest? — Produce a pro operations packet: correlated log sample, deploy checklist, rollback signals, and an incident review note.
Flashcards
- Pro operations: what decision does "Correlated structured logs" force you to make? Attach request, route, tenant, and operation context without leaking secrets. Evidence prompt: Add a correlation field to one request log and paste a sanitized log sample into the evidence journal.
- Pro operations: what decision does "Deploy smoke tests and rollback signals" force you to make? Define the checks that decide whether the release keeps receiving traffic or rolls back. Evidence prompt: Write a deploy checklist with exact health, log, metric, and rollback commands.
- Pro operations: what decision does "Incident review evidence" force you to make? Tie symptoms, timeline, impact, mitigation, and follow-up work to observable signals. Evidence prompt: Write a short incident note that links one symptom to a log line, health check, or SQL note.
- In .NET APIs, what should you remember about structured logging? structured logging matters here because it supports "Emit structured logs with correlation fields.".
- In .NET APIs, what should you remember about correlation id? correlation id matters here because it supports "Define deploy and rollback signals.".
- In .NET APIs, what should you remember about rollback signal? rollback signal matters here because it supports "Write an incident note tied to health and query evidence.".
- In .NET APIs, what should you remember about incident runbook? incident runbook matters here because it supports "Emit structured logs with correlation fields.".
Labs
- Ship a observability, deploys, and incident runbooks slice — Extend a production-grade ASP.NET Core order API with a small but reviewable feature that proves the lesson's architecture in code.
- Produce a pro operations packet: correlated log sample, deploy checklist, rollback signals, and an incident review note.
- Add a correlation field to one request log and paste a sanitized log sample into the evidence journal.
- Write a deploy checklist with exact health, log, metric, and rollback commands.
- Write a short incident note that links one symptom to a log line, health check, or SQL note.
- Add correlation fields to one request log.
- Define three rollback signals for the order API.
- The lab demonstrates the pro operations outcome without skipping earlier contract evidence.
- Each subtopic has a concrete artifact: Correlated structured logs, Deploy smoke tests and rollback signals, Incident review evidence.
- The review notes explain how this level changes ownership, verification, or operational risk.
Challenge
- Review-ready observability, deploys, and incident runbooks (Capstone) — Produce a pro operations packet: correlated log sample, deploy checklist, rollback signals, and an incident review note.
- All checklist items are either implemented or documented with a reason.
- The change can be understood from Orders/RequestLogging.cs plus one short note.
- The concept diagram names ownership, failure handling, and verification points.
- A teammate could run the verification steps without asking for hidden context.
Canonical lesson URL