Debug endpoints

Set OVERCAST_DEBUG=true to enable the /_overcast/debug namespace and request tracing. Every response carries a request ID (x-amzn-requestid for most services, x-amz-request-id for S3) which the trace endpoints below can look up.

Compatibility aliases

/_overcast/* is what to point new tooling at. Seven older URLs are served as well, because they are already written into healthchecks, wait strategies and test suites that predate them:

The health pair returns 200 whenever /_overcast/health does. This matters more than it looks: a container healthcheck that 404s marks Overcast unhealthy, and an orchestrator restarts it — which, on the default in-memory state backend, wipes every resource a deploy in flight had created.

The init pair needs no translation because Overcast’s status endpoint was built to LocalStack’s contract: the same BOOT/START/READY/SHUTDOWN stage names, the same UNKNOWN/RUNNING/SUCCESSFUL/ERROR script states. Both paths run the same handler, so they cannot drift apart.

The /_aws/ pair is what a test suite carried over from LocalStack asserts against, one assertion per test that sends an email or a message. The queue peek never consumes anything.

Three shapes differ from LocalStack’s, and a test asserting on them literally will notice:

• Region and RawData are absent from an /_aws/ses body. The capture does not hold a region, and cannot tell a raw send from a composed one.
• An empty queue is "Message": [] in the JSON form, not null.
• Receipt handles are the messages’ real ones rather than LocalStack’s placeholder, so one read from the peek can be passed to DeleteMessage.

Anything else under /_localstack/ or /_aws/ answers 404 with the Overcast endpoint that replaces it, rather than falling through to S3’s NoSuchBucket — see Endpoints and init hooks for the full table.

Trace retention

Traces are retained under three rules, so that the request explaining a failure is still there when you go looking, without your having configured anything first:

1. The newest OVERCAST_DEBUG_TRACE_BUFFER traces (default 1000) are always kept.
2. Beyond that, a burst is kept for OVERCAST_DEBUG_TRACE_WINDOW (default 1h), up to OVERCAST_DEBUG_TRACE_CEILING (default 10000). A cdk deploy pushes thousands of requests through in a couple of minutes, and the floor alone would keep the rollback traffic and discard the error that started it.
3. Traces that went wrong — a 4xx/5xx, an AWS error code, or a failed internal hop — are exempt from both, up to OVERCAST_DEBUG_TRACE_PINNED (default 1000). They are not exempt from the memory budget: under real pressure the oldest kept failures are surrendered last, after every ordinary trace above the floor.

Internal polling (health checks, the console’s own requests) is retained separately and can never evict a request you made. A trace records each internal service-to-service hop a request made, and captures a goroutine stack for the first 20 hops plus the first 20 hops that failed — a CloudFormation or CDK deploy dispatches hundreds of hops through one trace, and a stack for every one of them would cost more than it tells you. Hops past that budget show “Stack trace not captured” in the console.

See the environment variable reference for the full list of OVERCAST_DEBUG_TRACE_* variables and their defaults.

Related

• Troubleshooting — a symptom, and where its answer lives
• Log levels — OVERCAST_DEBUG and OVERCAST_LOG_LEVEL
• Checking a running daemon — the CLI over this surface