:py:mod:`starling_sim.utils.simulation_logging`
===============================================

.. py:module:: starling_sim.utils.simulation_logging

.. autoapi-nested-parse::

   Simulation logs offer an insight of the flow of events during the simulation run.
   They are displayed in chronological order and contain various information such as simulation setup,
   output generation or agent activity.

   Simulation logs are managed with the Python
   `logging <https://docs.python.org/3.6/library/logging>`_ library.

   *************************
   Simulation logging levels
   *************************

   In addition to the base levels of *logging*, we introduce two new ones:

   - An agent level that displays the agents' activities
   - An algorithm level that displays the algorithms' steps

   This results in the following available levels:

   .. list-table:: **STARLING LOGGING LEVELS**
      :widths: auto
      :header-rows: 1
      :align: center

      * - Level
        - Numeric value
      * - CRITICAL
        - 50
      * - ERROR
        - 40
      * - WARNING
        - 30
      * - INFO
        - 20
      * - AGENT
        - 15
      * - ALGO
        - 13
      * - DEBUG
        - 10

   The default logging level is 13.

   To run a simulation with a different logging level, you can use the ``-l`` (or ``--level``) option of main.py.
   For instance:

   .. code-block:: bash

       python3 main.py data/models/SB_VS/example_nantes/ -l 20

   ******************
   Simulation loggers
   ******************

   We also create specific loggers for the :class:`~starling_sim.basemodel.trace.trace.Traced` and
   :class:`~starling_sim.basemodel.algorithms.algorithm.Algorithm` classes with
   different logging formats, in order to display additional information (such as the simulation time). For instance:

   .. code-block:: text

       AGENT :: [50904], S1 : Picked up u-11

   In order to display logs, instances of these classes call their
   internal method log_message so the relevant information is fetched
   directly from their attributes and a default level is applied.

   These additional loggers may also be used by any module developed around
   Starling to display simulation logs.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   starling_sim.utils.simulation_logging.setup_logging
   starling_sim.utils.simulation_logging.new_traced_logger
   starling_sim.utils.simulation_logging.new_algo_logger
   starling_sim.utils.simulation_logging.new_blank_logger



Attributes
~~~~~~~~~~

.. autoapisummary::

   starling_sim.utils.simulation_logging.BASE_LOGGER_FORMAT
   starling_sim.utils.simulation_logging.DEFAULT_LOGGER_LEVEL
   starling_sim.utils.simulation_logging.TRACED_LOGGER_FORMAT
   starling_sim.utils.simulation_logging.ALGO_LOGGER_FORMAT
   starling_sim.utils.simulation_logging.BLANK_LOGGER_FORMAT
   starling_sim.utils.simulation_logging.TRACED_LOGGER
   starling_sim.utils.simulation_logging.ALGO_LOGGER
   starling_sim.utils.simulation_logging.BLANK_LOGGER


.. py:data:: BASE_LOGGER_FORMAT
   :value: '%(levelname)s :: %(message)s'

   

.. py:data:: DEFAULT_LOGGER_LEVEL
   :value: 13

   

.. py:function:: setup_logging(logger_level)

   Setup the logging configuration for the run.

   :param logger_level: integer describing the logger level


.. py:data:: TRACED_LOGGER_FORMAT
   :value: '%(levelname)s :: [%(timestamp)s], %(id)s : %(message)s'

   

.. py:function:: new_traced_logger()

   Create and return a logger for the traced agents.

   :return: Logger object from the logging library


.. py:data:: ALGO_LOGGER_FORMAT
   :value: '%(levelname)s :: %(alg_name)s : %(message)s'

   

.. py:function:: new_algo_logger()

   Create and return a logger for the simulation algorithms.

   :return: Logger object from the logging library


.. py:data:: BLANK_LOGGER_FORMAT
   :value: '%(message)s'

   

.. py:function:: new_blank_logger()

   Create and return a logger without prefix.

   :return: Logger object from the logging library


.. py:data:: TRACED_LOGGER

   

.. py:data:: ALGO_LOGGER

   

.. py:data:: BLANK_LOGGER