Metadata-Version: 2.1
Name: cazoo_logger
Version: 0.9.0
Summary: Super-opinionated structured logger for AWS lambda
Home-page: https://github.com/Cazoo-uk/py-logger
Author: Bob Gregory
Author-email: bob.gregory@cazoo.co.uk
License: MIT
Description: Intro, in which opinions are had
        --------------------------------
        
        Cazoo-Logger is a deeply opinionated structured logger for Python on AWS Lambda.
        
        Cazoo-Logger owes a debt to `aws_lambda_logger`_ which is both less opinionated, and probaby better suited to your particular use-case than this library. Go check it out.
        
        Basic Usage
        -----------
        
        The Cazoo Logger module exposes a single function `config` that sets up the logger for use.
        
        >>> import cazoo_logger
        >>> cazoo_logger.config()
        
        By default this configures the root logger at INFO level, writing to a special JSON formatter.
        
        To obtain a logger instance, call the appropriate fromContext function with your incoming event and context:
        
        >>> def handler(event, context):
        ...     logger = cazoo_logger.fromContext(event, context)
        ...     logger.info('sup?')
        ...
        
        This will result in well-formatted json messages with a documented schema.
        
        ::
        
          {
              "msg": "sup?",
              "context": {
                  "request_id": "abc123",
                  "function": {"name": "do-things", "version": "0.1.2.3"},
                  "sns": {
                      "id": "66591d01-0241-5751-bb17-586e5a6dcf91",
                      "topic": "arn:aws:sns:us-east-1:12345678912:bucket-o-stuff",
                      "type": "Notification",
                      "subject": "Amazon S3 Notification",
                  },
              }
          }
        
        If you don't have an AWS context and event, you can construct a logger with no context
        
        >>> logger = cazoo_logger.empty()
        
        Logging Errors
        --------------
        
        Logging caught errors is as simple as setting the exc_info kwarg to True on the log call.
        
        >>> try:
        ...     raise ValueError("What in the heck do you call that?")
        ... except:
        ...     logger.warn("I dunno man, looks pretty sketchy to me", exc_info=True)
        ...
            {"msg": "I dunno man, looks pretty sketchy to me", "data": {"error": {"name": "ValueError", "message": "What in the heck do you call that?", "stack": "Traceback (most recent call last):\n  File \"<stdin>\", line 2, in <module>\nValueError: What in the heck do you call that?"}}}
        
        
        Logging additional data
        -----------------------
        
        You might want to include additional structured data in your logs. Any values you pass to the `extra` kwarg will be json serialised into the `data` section of your log line.
        
        >>> logger.info("I did a query", extra={'sql': {'query': 'select * from table where field = ?', 'parameters': [123] }})
        {"msg": "I did a query", "data": {"sql": {"query": "select * from table where field = ?", "parameters": [123]}}}
        
        You can also use the `with_data` method. This method returns a new logger instance with the data section pre-populated.
        
        >>> new_logger = logger.with_data(sql={'query': 'select * from foo where bar = ?', 'parameters':[234]})
        >>> new_logger.debug('doin a query')
        {"msg": "doin a query", "data": {"sql": {"query": "select * from foo where bar = ?", "parameters": [234]}}}
        >>> new_logger.error('oh noes! the query did not work!')
        {"msg": "oh noes! the query did not work!", "data": {"sql": {"query": "select * from foo where bar = ?", "parameters": [234]}}}
        
        
        Logging additional context
        --------------------------
        
        Similarly you might want to add more data to the context section of your log event.
        
        >>> new_logger = logger.with_context(request_id='abc-123')
        >>> new_logger.info('handling request')
        {"msg": "handling request", "context": {"request_id": "abc-123"}}
        
        .. _cazoo logger: https://www.npmjs.com/package/cazoo-logger
        .. _aws_lambda_logger: https://pypi.org/project/aws-lambda-logging
        
        Additional Log Levels
        ---------------------
        The add_logging_level function allows you to add custom log levels to the logger.
        So for example a level of "TRACE" could be added at 15 to provide a level of logging is
        between DEBUG and INFO.
        
Platform: UNKNOWN
Description-Content-Type: text/x-rst
