improv adopt logging best practices

[heitorlessa]

Issue #, if available: #16 #21

BREAKING CHANGE

logger_setup and logger_inject_lambda_context had to be deprecated in favour of Log class - The user experience remains the same so it's easier swap. If you try to use any of these functions it'll raise an DeprecationWarning exception.

While we're on Beta we strive to make backwards compatible changes, however this wasn't the case - The former implementation impact all loggers (root) and can't be easily updated to allow both decorators to work cleanly, and without side effects.

UX

UX stays the same except we now use a class Logger instead of functions.

from aws_lambda_powertools.logging import Logger

logger = Logger(service="payment", level="INFO") 
# logger = Logger() # implicit config via env vars 

@logger.inject_lambda_context
def handler(event, context)
  logger.info("Collecting payment")
  logger.info({ 
    "operation": "collect_payment",
    "charge_id": event['charge_id'] 
  })

NEW - Appending new keys to structured log

...
@logger.inject_lambda_context
def handler(event, context):
    if "payment_id" in event:
        logger.structure_logs(append=True, payment_id=event["payment_id"])
    logger.info("Collecting payment")

Description of changes:

• Use a Null Handler to cut noise in customers' logging
• Create top-level logger aws-lambda-powertools
• Refactor Lambda Logging module to prevent root logging changes
• Prevent unnecessary exceptions from Lambda Logging module (e.g. KeyError)
• Create Logger class and reuse same UX as before
• Raise deprecated exception for standalone logger_setup, and logger_inject_lambda_context
• Update docstring
• Allow appending log keys to structured log
• Update docs to reflect the change
• Document package logger and how to enable debug
• Update tests
• Talk about deprecation and root logger

Optionally

• [x] Create a POWERTOOLS_LOG_LEVEL environment variable
• [x] Set package log level if POWERTOOLS_LOG_LEVEL is set
• [ ] Set boto logs via env var
  • Best handled by customer's code
• [ ] Accept an existing logger in logger setup
  • KISS
• Complete coverage

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[heitorlessa]

@marcioemiranda - Let me know if I missed anything else as I'm working on logger this week to fix logging level along with other suboptimal practices

[heitorlessa]

@jfuss When you can, may I have your review? This adopts the logging best practices as we discussed

[jfuss]

Is there a way for a customer to provider their own JsonFormatter?

[heitorlessa]

No - We limit to our own to prevent additional complexity. What we allow is the ability to add additional keys to their structured logger either at logger creation or after.

logger = Logger(request_id="request id!", another="value")
logger = Logger()
logger.structure_logs(request_id="request id", another="value")

Would be happy to hear otherwise.

[jfuss]

What do additional keys have to do with how the Json data is formatted? I am thinking of the case where Company X has a different way they want the data to be formatted, which doesn't have anything to do with what the data actually is in the Json. Or maybe they don't want Json at all and prefer XML (for whatever reason). I don't think this blocks anything here but something to maybe think about in the future.

[jfuss]

Aren't they kind of already removed since those methods just raise an exception?