How to Design Structured API Logs That Separate Request and Delivery Events

Effective API logging for notification services requires recording two distinct events: one at the HTTP request boundary and one for each asynchronous delivery attempt, linked by a stable notification ID. Treating both as a single log entry creates misleading dashboards and weakens incident investigations, particularly when push delivery happens in a separate process seconds after the API response. Key fields for the request event include route, status code, duration, and notification ID, while delivery events should capture attempt number, channel, outcome, and a bounded error category. Three core invariants must be maintained — notification_id tracks the business operation, request_id tracks the HTTP exchange, and duration_ms must have a clearly defined boundary — since silently redefining a field corrupts cross-deployment comparisons. Engineers must also account for failure gaps, such as distinguishing whether a notification was never created versus created but not yet attempted, and should document the actual durability guarantees of their log transport rather than assuming completeness.