# `TwitchLoggingCommonLoggers`

This package represents a simple implementation of [TwitchLogging](https://code.amazon.com/packages/TwitchLogging/trees/mainline).
It includes a basic JSON logger that formats and outputs logs as JSON and a decorative logger that can wrap the JSON logger,
allowing key, value pairs to be maintained across multiple log statements.

This library is intentionally small and provides a basic implementation that can commonly be used by AWS Lambda, where
std.out logs are sent to CloudWatch. 

We encourage customers to implement their own solution if they want a more robust library as we acknowledge that many
teams have their own preferences or custom loggers. We just ask teams to follow best practices of outputting structured 
logs and ensuring compatibility with [Scroll](https://w.amazon.com/bin/view/Scroll/).

For more information on logging, please see the [Fulton Logging Doc](https://docs.fulton.twitch.a2z.com/docs/logging.html).

## Non-blocking logging
Fulton-generated ECS services use the awslogs log driver to send all bytes written to stdout and stderr in the container to CloudWatch Logs. All ECS services are configured to use Docker's default 'blocking' mode when delivering logs from a container to the log driver. The awslogs log driver has a maximum throughput at which it can consume logs from a container. If a container running in 'blocking' mode is producing log entries faster than the log driver can consume them, Docker will exert backpressure causing programs in the container to block when writing to stdout. This behaviour will cause programs to unexpectedly block on otherwise benign logging calls, resulting in increased per-request latency.

If a service wishes to guarantee that its logging calls will not block, they may configure their logger to wrap `os.Stdout` in a `RingBufferWriter`, to instead drop old log messages when the log driver falls behind. See `ring.go` in this package for more details.


## Referring to this package
To refer to this dependency, refer to its alias of `code.justin.tv/amzn/TwitchLoggingCommonLoggers`

## Help
For help using this package, please ping the [#fulton](https://twitch.slack.com/messages/C9BUPDUC8) Slack channel
