Why

• Enable searching logs for specific requests for debugging and analytics.

How

• Calculate a request id when the message is received.
• Propagate that request id along with the request so that it can be used for logging and auditing.
• Return the id in the response as a header and/or as part of the response body.

Why

How

Progress

Why

Because it's a Damn Good Thing.

See, for example: https://honeycomb.io/blog/2018/02/structured-logging-and-your-team/

How

As a developer, I should be able to easily log...

• ... a message
• ... at a particular logging level
• ... together with a list of string-value pairs that will be included as fields in my structured log

E.g.,

log.info(
  "ReceivedFooMessage",
  "userId" -> request.user.id,
  "data" -> request.data
)

Ideally, this should support more than simple string-string pairs. Ideally anything I can serialize to JSON should be acceptable as a field value, so that I can not just strings, numbers, and booleans, but also arrays and objects. This more-or-less rules out anything MDC-based.

It would also be nice for the logging context to be functional, rather than reliant on external state. Maybe something like:

val localLog = log.withContext("userId" -> request.user.id)

localLog.info("ReceivedFooMessage") // Would include request.user.id

Progress

Why

We want to be able to inject configuration through system properties and/or environment variables to customize the application for each environment.

How

• Likely based on Lightbend Config and PureConfig.
• Should support some concept of "profiles"

Progress

Why

Error messages should be consistent and structured.

• As a client of the API, I want messages that clearly communicate what went wrong so that I can distinguish between different errors and potentially communicate relevant details back to the user.
• As a developer of the API, when somebody sends me an error message I want there to be enough information that I can
  • see what request they actually made
  • find the path of the request in the logs

How

• Error messages should be returned as JSON.
• Messages should include the following fields at a minimum
  • request method
  • request path
  • request id (users do not often include the headers in bug reports)
  • response status code
  • timestamp of the request

Not included for now:

• Request headers, query parameters, request body: Potentially too much information, including sensitive information

Future Work

• Once we have authentication/authroization, the scopes and user id the request was made with should be included to help with debugging auth-related errors.

Why

How

Progress