app/utils/debug_log_formatter.ts is pre-populated with 12 lines of generic timestamp formatting code. For months, you’ve relied on this formatter to standardize logs across all your backend services, but you’ve noticed it’s getting harder to resolve old bug reports because the logs lack consistent, actionable context. The current template only includes a timestamp and plaintext message, so when a user reports a bug that first occurred three weeks prior, you have to sift through thousands of unstructured lines to find the sequence of events that triggered the error, if you can find them at all.
Broken core line
The core flaw sits on line 7 of the file: the line that constructs the final log output string only concatenates the timestamp and input message, with no space for standard metadata. Right now, when you log a payment processing error, the output reads `2024-05-12T14:32:11.456Z: error processing charge` with no way to tie that line to a specific user request, the action that triggered the error, or the final outcome of the request. This means you can’t filter logs by request ID to pull the full flow of a single user’s session, and you can’t aggregate logs by action to see how often a specific workflow fails. Illustrative example: 72% of your debug logs are unsearchable after 48 hours because they lack structured context that ties individual events to a single user session or request flow. You recently spent two hours tracing a failed refund request, only to realize you couldn’t confirm the root cause because none of the related logs included a shared identifier to link the payment webhook, refund processing worker, and user notification service events together. Fixing this line gives you that consistent link across all logs, so you can resolve old bugs as easily as new ones.
Untouched existing logic
You don’t need to rewrite the entire file to fix the log structure. The first six lines of code handle ISO 8601 timestamp formatting with millisecond precision and UTC offset, which is already compatible with your log management tool’s parsing rules, so you leave those entirely untouched. Lines 10 through 12 contain logic to append error stack traces to logs with a `severe` level, which works exactly as intended for critical error debugging, so you don’t modify that code either. The exported function signature on line 8 already accepts an optional context object as its third parameter, a change you added three months ago when you first considered adding structured logging, so you don’t need to adjust the function inputs or update every existing call to the logger across your codebase. Making changes to any of these sections would break existing logging functionality or require unnecessary refactoring across half a dozen services, so you keep them exactly as they are.
Targeted formatter edit
You update the core log construction logic with five simple, targeted steps to add the four required fields (time, request id, action, outcome) to every log line without breaking existing functionality:
- Add a destructuring assignment at the very start of the `formatLog` function to pull the required fields from the context object, with fallback values for when the context is missing or incomplete: `const { requestId = “no-request-id”, action = “unspecified-action”, outcome = “unknown-outcome” } = context || {};` The fallbacks ensure the logger never throws an error if a service forgets to pass context, and they make it easy to spot logs that are missing critical context for later cleanup.
- Modify the log output line on line 7 to include the four required fields in order, separated by pipe characters for easy, consistent parsing by your log management tool: `const logMessage = `${timestamp} | ${requestId} | ${action} | ${outcome} | ${level}: ${message}`;` The pipe delimiter is rare in normal log messages, so you don’t have to worry about accidental parsing breaks for most use cases.
- Add a single guard clause right after the destructuring assignment to replace any pipe characters in input values with underscores, to eliminate the small risk of parsing breaks from messages that include pipes: `[requestId, action, outcome, message].forEach((field: string) => field.replace(/|/g, “_”));`
- Test the formatter with three sample inputs to confirm it works as expected: one with a full context object, one with a partial context object, and one with no context at all. All three produce valid, structured log lines with no missing required fields, and the fallback values show up as expected for incomplete inputs.
- Add a short JSDoc comment above the exported function to document the three required context fields, so other contributors on your team know what values to pass when calling the logger for new workflows.
Deployment scope
This formatter is imported as a shared utility by every backend service in your monorepo, so once you commit the changes to your main branch, it rolls out automatically to your public API, payment processing worker, notification service, and admin dashboard backend as part of your regular weekly deployment. The file stays in the `app/utils/` directory of your private monorepo, with no public exposure, so you can update the log template at any time without modifying individual service logging code. The structured log output feeds directly into your existing cloud log management tool, so you can set up saved searches for specific actions, outcomes, or request IDs immediately after deployment, no extra configuration required. This structured logging pattern aligns with the observability best practices covered in Build Next Stack’s backend foundation guides. You also set up a simple dashboard in your monitoring tool that tracks the share of logs with missing request IDs, so you can gradually update older logging calls to pass the required context over time without a full rewrite.
Excluded extra content
You intentionally keep the log template minimal to ensure it stays useful for months, and you avoid adding extra fields or logic that would reduce its long-term value. You don’t add sensitive user data like email addresses, full names, or payment details to the base template, because including that data would force you to delete logs after 30 days to comply with global data privacy regulations, instead of keeping them for 6 months for debugging. You don’t add extraneous fields like user agent strings, IP addresses, or location data to the base template, because those are only needed for specific debugging use cases, and adding them to every log line bloats storage costs and slows down search queries. You don’t add custom formatting for specific log levels, because that would break the consistent structure that lets you search across all log levels in a single query. You also don’t add automatic redaction logic to this file, because that belongs in a separate logging middleware that runs before the formatter, so you can adjust redaction rules for specific services without touching the core log structure that all services rely on.
Next file open
You open this exact file again six weeks from now, when you’re troubleshooting a reported bug where users with expired subscriptions are still getting access to paid premium content. You pull logs from the 4-week-old window when the first user reported the bug, and you search for all logs tied to the affected user’s request ID, which you pull from their support ticket. Within seconds, you see that every log line for the user’s session includes the `subscription_status_check` action with an outcome of `success`, even though the user’s subscription expired two weeks prior. You cross-reference those lines with the payment service logs for the same request ID, and you immediately spot that the subscription status check was using a cached value that hadn’t been updated after the user’s subscription expired. You find the root cause in 12 minutes, instead of the 2 hours it would have taken you to sift through unstructured logs before you updated the formatter. You add a note to the JSDoc comment that the `subscription_status_check` action should include a `cache_hit` flag in the context for extra clarity, but you leave the core four fields of the log template entirely intact, because they’re working exactly as you designed them to, even for bugs that show up months after you deploy the change.