Document recommended style for logging calls

[everett1992]

Describe the feature

The type of logger in @aws-sdk/types is very open and allows any arguments.

info: (...content: any[]) => void;

Popular logging libraries use different argument patterns and orders. Some expect meta objects first, some expect var args, some support callbacks.

• winston expects (string, meta)
• pino expects (meta, string)

logger.info("something went wrong", err)

pino

{"level":30,"time":1668795910526,"pid":1870501,"hostname":"...","msg":"something went wrong"}

winston

{"level":"info","message":"something went wrong","stack":"Error\n    at Object.<anonymous> (test.ts:8:13)\n    ..."}

logger.info(err, "something went wrong")

pino

{"level":30,"time":1668796367853,"pid":1874536,"hostname":"...","err":{"type":"Error","message":"message","stack":"Error: message\n    at Object.<anonymous> (test.ts:8:13) ...},"msg":"something went wrong"}

winston

{"level":"info","message":{}}

As you can see loggers depend on the order of arguments to include the error and stack trace.

Use Case

When writing middleware I want to know how I should format my log calls.

• what order should I put messages and context objects
• should I wrap context in a object or use varargs

• what levels should I use (the style guide should give examples of info, debug, trace, warn, error... so middleware are consistent)

  When passing a logger to a client constructor I want to know logs will be properly formatted.

Proposed Solution

Define a style guide covering recommended log implementations, order and types of parameters, and log levels. Potentially narrow the typescript type for logger to match a specific order. Potentially create wrappers or examples of converting a logger to the expected format.

Other Information

No response

Acknowledgements

• [X] I may be able to implement this feature request
• [X] This feature might incur a breaking change

SDK version used

3.x

Environment details (OS name and version, etc.)

N/A

[ghost]

I would define a universal interface for logging, so that customers can write adapters for whatever libraries they prefer. SDK might provide 1-2 adapters for most popular logging frameworks.

[github-actions[bot]]

Greetings! We’re closing this issue because it has been open a long time and hasn’t been updated in a while and may not be getting the attention it deserves. We encourage you to check if this is still an issue in the latest release and if you find that this is still a problem, please feel free to comment or open a new issue.

[github-actions[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs and link to relevant comments in this thread.