.. currentmodule:: event_collector

Logger
======

**Source code:** `event_collector.logger.py`

.. py:module:: event_collector.logger

   This module contains logging management functions for event-collector.

.. pull-quote::

   The ``event_collector`` library uses the *structlog* loggers from this
   module to output log entries. All log entries are in JSON format.


Normally, you would not need to interface with this module. However,
the loggers are independent of the rest of the ``event_collector``
library and can be used as a general JSON-formatted logger in your
application to replace the standard ``logging`` library.

The log level can be set using the environment variables ``DEBUG`` and
``LOG_LEVEL``. If ``DEBUG`` is exported as ``true``, ``yes``, or
``1``, the default log level will be set to "debug." If ``DEBUG`` is
not set or is not set to True, then the log level will depend on the
exported value of ``LOG_LEVEL``. If ``LOG_LEVEL`` is unset, the
default log level will be set to the ``DEFAULT_LOG_LEVEL`` constant
value ("info").

Example::

   DEBUG=true
   export DEBUG

   # or

   LOG_LEVEL="DEBUG"
   export LOG_LEVEL


Constants & Types
-----------------

.. autodata:: DEFAULT_LOG_LEVEL

.. autotype:: AppLogger


LogRegistry
-----------
.. autoclass:: event_collector.logger.LogRegistry
   :members: add_logger, get_logger
   :member-order: bysource


NullLogger
----------

.. autoclass:: event_collector.logger.NullLogger


Functions
---------

.. autofunction:: event_collector.logger.set_log_registry

.. autofunction:: event_collector.logger.get_log_registry

.. autofunction:: event_collector.logger.get_logger


Example Usage
-------------

Output a JSON log entry using the default ``event_collector`` logger::

    >>> from event_collector.logger import get_logger
    >>> log = get_logger()
    >>> log.info("example log entry", value="log output")
    {"logger":"event-collector","value":"log output","event":"example log entry","level":"info","timestamp":"2026-03-31T02:20:47.335852Z"}