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.
- Design and implement a small but professional ASP.NET Core API.
- Use persistence, validation, tests, logging, configuration, and package hygiene.
- Explain architectural choices and operational tradeoffs.
Concepts
- structured logging
- correlation id
- rollback signal
- incident runbook
- Final Project
- Project brief
- Implementation outline
- Modern C# and .NET foundations
- Guided practice
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.
- Catalog API Capstone: Project brief (concept, 120 min) — Build a Catalog API for managing products and categories. The API should expose endpoints for listing, creating, updating, and retiring products. It should validate inputs, persist data, include tests, and use a clear project structure.
- Retained source example: Required capabilities
GET /products?category=&page=&pageSize=
GET /products/{id}
POST /products
PUT /products/{id}
POST /products/{id}/retire
These endpoints are enough to exercise routing, validation, DTOs, persistence, and tests.
- Catalog API Capstone: Implementation outline (walkthrough, 120 min) — Use a solution with API, application/domain, infrastructure, and test projects, or a vertical-slice API with clear feature folders. Use EF Core with migrations, validated options, structured logging, and focused tests. The guided runner should verify deterministic metadata such as names, endpoint list, and selected patterns; it should not execute arbitrary submitted server code.
- Retained source example: Product contract sketch
public sealed record CreateProductRequest(
string Name,
string Category,
decimal Price);
public sealed record ProductResponse(
Guid Id,
string Name,
string Category,
decimal Price,
bool IsRetired);
Contracts are explicit and stable at the HTTP boundary.
- Catalog API Capstone: practices and mistakes (review, 5 min) — Retained guidance from the legacy PTesting lesson.
- Practice: Keep the API surface small and complete before adding optional features.
- Practice: Write tests for validation, not-found behavior, successful creation, and retirement rules.
- Practice: Use migrations and seed data intentionally.
- Practice: Include a short README with setup, commands, and design choices.
- Avoid: Building a large framework before implementing the required endpoints.
- Avoid: Skipping tests for failure paths.
- Avoid: Hard-coding configuration that should be environment-specific.
- Avoid: Leaving generated build artifacts in source control.
- Catalog API Capstone: references (review, 2 min) — Original references retained from the legacy library.
- Minimal APIs: https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis
- Testing ASP.NET Core: https://learn.microsoft.com/aspnet/core/test/
- EF Core documentation: https://learn.microsoft.com/ef/core/
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.
- Required capabilities — These endpoints are enough to exercise routing, validation, DTOs, persistence, and tests.
- Retained source code:
GET /products?category=&page=&pageSize=
GET /products/{id}
POST /products
PUT /products/{id}
POST /products/{id}/retire
- Explain the expected behavior.
- Compare the example with the canonical PTLearn implementation.
- Product contract sketch — Contracts are explicit and stable at the HTTP boundary.
- Retained source code:
public sealed record CreateProductRequest(
string Name,
string Category,
decimal Price);
public sealed record ProductResponse(
Guid Id,
string Name,
string Category,
decimal Price,
bool IsRetired);
- Explain the expected behavior.
- Compare the example with the canonical PTLearn implementation.
- Suggested verification commands — These commands check formatting, tests, and release packaging in a normal local or CI workflow.
- Retained source code:
dotnet format --verify-no-changes
dotnet test
dotnet publish Catalog.Api -c Release
- Explain the expected behavior.
- Compare the example with the canonical PTLearn implementation.
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.
- List capstone deliverables: List the three required capstone evidence items: endpoints, tests, and architecture note.
- Starter code: deliverables = ____
- Expected output: endpoints, tests, architecture note
- Hint: The grader validates deterministic metadata about the project plan and submitted files, not arbitrary server execution.
- Reference solution: Submit endpoint list, passing test summary, and a short architecture note.
- Accepted answers: endpoints tests architecture note | endpoints, tests, architecture note
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.
- What should the final project architecture note explain? — A useful architecture note explains tradeoffs so another engineer can maintain the project.
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