.. _api_logging:

Logging Module (biallelic.logging)
==================================

The logging module provides hierarchical logging capabilities for the
biallelic analysis pipeline.

.. automodule:: biallelic.logging
   :members:
   :undoc-members:
   :show-inheritance:

Overview
--------

This module provides two logger classes:

- **SimpleLogger**: Main logger with support for creating sublogs
- **ExtendedLogger**: Low-level logger for detailed logging control

SimpleLogger is recommended for most use cases, while ExtendedLogger
provides fine-grained control over logging behavior.

Basic Usage
-----------

Creating a logger for your analysis:

.. code-block:: python

    from biallelic.logging import SimpleLogger
    import logging

    # Create main logger
    logger = SimpleLogger("my_analysis", "/path/to/logs")

    # Log messages
    logger.log.info("Starting analysis")
    logger.log.debug("Debug information")
    logger.log.error("Error message")

    # Create sublogs for different analysis stages
    stage1_log = logger.add_log("stage1")
    stage1_log.log.info("Stage 1 processing")

    stage2_log = logger.add_log("stage2", level=logging.DEBUG)
    stage2_log.log.debug("Detailed stage 2 information")

Output
------

SimpleLogger creates two output streams:

1. **Log File**: ``<logs_dir>/<logger_name>.log``
   - Contains all messages at configured level
   - Includes timestamps and severity

2. **Console Output**: stdout/stderr
   - Shows same messages as log file
   - Allows real-time monitoring

Configuration
-------------

Set logging level when creating logger:

.. code-block:: python

    import logging
    from biallelic.logging import SimpleLogger

    # DEBUG level - most verbose
    debug_logger = SimpleLogger("debug", "/logs", level=logging.DEBUG)

    # INFO level - standard
    info_logger = SimpleLogger("analysis", "/logs", level=logging.INFO)

    # WARNING level - only important messages
    warn_logger = SimpleLogger("warnings", "/logs", level=logging.WARNING)

Log Format
----------

Log messages include:

- **Timestamp**: ``YYYY-MM-DD HH:MM:SS,mmm``
- **Logger Name**: Hierarchical logger identifier
- **Level**: DEBUG, INFO, WARNING, ERROR, CRITICAL
- **Message**: The log message

Example log output:

.. code-block:: text

    2025-10-29 12:34:56,789 - my_analysis - INFO - Starting analysis
    2025-10-29 12:34:57,123 - my_analysis.stage1 - DEBUG - Processing file 1 of 100
    2025-10-29 12:35:02,456 - my_analysis.stage1 - ERROR - Failed to read file: /path/to/file

Advanced Usage
--------------

Creating multiple independent analysis stages:

.. code-block:: python

    from biallelic.logging import SimpleLogger

    # Main analysis logger
    main_logger = SimpleLogger("biallelic_run", "/path/to/logs")

    # Sub-loggers for each stage
    refs_logger = main_logger.add_log("loading_refs")
    data_logger = main_logger.add_log("loading_data")
    discovery_logger = main_logger.add_log("discovery")
    output_logger = main_logger.add_log("output")

    # Each produces separate log entries under main logger
    refs_logger.log.info("Loaded genes: 20000")
    data_logger.log.info("Loaded samples: 500")

See Also
--------

- :ref:`api_bi`: Orchestrator using logger
- :ref:`api_misc`: Utility functions
- Python logging: https://docs.python.org/3/library/logging.html