Zack Williams | 4113213 | 2018-10-19 12:14:45 -0700 | [diff] [blame^] | 1 | multistructlog |
| 2 | ============== |
| 3 | |
| 4 | This module is a thin wrapper around Structlog that sets and provides defaults |
| 5 | for sending logs to one or more logging destinations with individual formatting |
| 6 | per destination. |
| 7 | |
| 8 | The API consists of a single function: ``create_logger()``. |
| 9 | |
| 10 | Args: |
| 11 | logging_config (dict): Input to logging.config.dictConfig |
| 12 | level(logging.loglevel): Overrides logging level for all loggers (not handlers!) |
| 13 | |
| 14 | Returns: |
| 15 | log: structlog logger object |
| 16 | |
| 17 | It can be invoked as follows: |
| 18 | |
| 19 | logging_config = ... |
| 20 | |
| 21 | log = multistructlog.create_logger(config, level=logging.INFO) |
| 22 | log.info('Entered function', foo='bar') |
| 23 | |
| 24 | To create a ``logging_config`` dictionary, see these docs: |
| 25 | |
| 26 | https://docs.python.org/2.7/library/logging.config.html#logging.config.dictConfig |
| 27 | http://www.structlog.org/en/stable/standard-library.html#rendering-using-structlog-based-formatters-within-logging |
| 28 | |
| 29 | There are no required arguments to `create_logger()` - any missing parts of the |
| 30 | config will be filled in with defaults that print structured logs to the |
| 31 | console. |
| 32 | |
| 33 | If you don't specify a ``formatters`` section in your config, three will be |
| 34 | created which can be used in handlers: |
| 35 | |
| 36 | - ``json``: renders one JSON dictionary per message |
| 37 | - ``structured``: prints structured logs with the ``structlog.dev.ConsoleRenderer`` |
| 38 | - ``structured-color``: same as ``structured`` but in color |
| 39 | |
| 40 | If you don't specify a ``handlers`` section, a handler will be added that logs |
| 41 | to console with ``logging.StreamHandler`` with format ``structured`` at level |
| 42 | ``DEBUG``. |
| 43 | |
| 44 | If you don't specify a ``loggers`` section, a default logger (empty string) |
| 45 | will be created with all items in ``handlers`` added to it, with a level of |
| 46 | ``NOTSET`` (every level printed). |
| 47 | |
| 48 | When setting log level, the higher of ``logging_config['loggers'][*]['level']`` |
| 49 | and ``logging_config['handlers'][*]['level']`` is used. The ``level`` parameter |
| 50 | overrides the ``loggers`` value of level, not the ``handlers`` one. |
| 51 | |
| 52 | If the handler's level is set to ``DEBUG`` but the logger's level is set to |
| 53 | ``ERROR``, the handler will only log ``ERROR`` level messages. |
| 54 | |
| 55 | Multistructlog also adds a ``TRACE`` log level (integer level 5) that is below |
| 56 | "DEBUG" to both standard library ``Logger`` and Structlog ``BoundLogger``. |
| 57 | |
| 58 | List of standard logging levels: |
| 59 | https://docs.python.org/2.7/library/logging.html#logging-levels |