Operational Code

Overview

Operational code is production code that tells you how it's doing without anyone asking. Every function emits metrics, every request leaves a trace, every error provides context. At Amazon, "it works on my machine" is meaningless—what matters is whether it works in production right now, under load, at 3 AM.

Writing operational code means embedding observability into the implementation from the first line. Not as an afterthought, not as a "hardening sprint" task—from the start. When an alarm fires, operational code gives you the dashboard, the log query, and the trace ID to diagnose the issue in minutes, not hours.

The principle is simple: if you can't observe it, you can't operate it. If you can't operate it, you shouldn't ship it.

When to Use

• Writing any production code (this is not optional)
• Implementing new API endpoints or message handlers
• Adding external service calls or database queries
• Handling errors, retries, or fallback paths
• Implementing feature flags or configuration changes
• Building background jobs, queues, or async workflows

Amazon Context

Amazon operates thousands of services at massive scale. When something goes wrong, the operator (often the developer who wrote the code, on-call at 2 AM) needs to answer three questions in under 5 minutes:

1. What is broken? (Metrics and alarms tell you)
2. Since when? (Dashboards with time correlation tell you)
3. Why? (Structured logs and traces tell you)

Services that don't emit proper telemetry become operational black holes—they break, nobody knows why, and recovery takes hours of guessing. Amazon's operational bar requires that every service ships with dashboards, alarms, and runbooks before launch (enforced through ORR—Operational Readiness Review).

Observability platforms (metrics, tracing, logging) provide the infrastructure. But the instrumentation must live in the code. No external tool can observe what the code doesn't emit.

The Process

1. Structured Logging (JSON)