Logs, metrics, and evidence-led diagnosis
Connect symptoms to evidence with request IDs, Workers Logs, metrics, and structured errors.
Edited and verified by Orange Book Editorial Team ·
The goal is not more logs
A request ID should connect entry, important branches, downstream calls, and final status without recording secrets or sensitive content.
Minimum event shape
const requestId = request.headers.get('cf-ray') ?? crypto.randomUUID();
console.log(JSON.stringify({
event: 'request_complete',
requestId,
route: new URL(request.url).pathname,
status: 200,
}));Log stable fields only. URL queries, Authorization, cookies, form bodies, and model prompts stay out by default; any exception needs field-level redaction and retention review.
Three evidence layers
| Layer | Answers | Examples |
|---|---|---|
| Logs | What happened to this request? | Branch, error class, downstream status |
| Metrics | How large is the problem and when did it start? | Requests, errors, CPU, latency distributions |
| Correlation | How do components connect? | Ray ID and an application request ID |
Failure drill
Inject a controlled failure
Only in local or preview, make one test route return 503 without unknown production side effects.
Detect it in metrics
Confirm the error-rate change, then narrow by time range and Worker version.
Locate it in logs
Use requestId to find the route and error category. Return a stable client error code—not a stack trace, SQL, or upstream credentials.
Remove and retest
Remove the test switch, confirm the success path and metrics recover, and add the procedure to a runbook.
Primary sources
Did this page help you complete your goal?
Beta feedback is generated in this browser and is never uploaded automatically.
Release a D1 database: migrations, local verification, and Time Travel
Separate local and remote D1 state, release compatible schema migrations, and reserve Time Travel for human-approved recovery.
Testing, preview environments, and gradual release
Protect Cloudflare releases with unit tests, workerd integration, isolated bindings, and evidence-backed rollback.