Application Tracing

Logger Engine

This is a detailed and didactic documentation of the LoggerEngine class, designed to be the core of traceability and monitoring for Python applications.

On this page

    #Overview

    LoggerEngine is not just a simple message formatter; it is a telemetry orchestrator. Its main function is to centralize the capture of system events and decide, based on dynamic settings (environment variables or instance parameters), where this data should go: console, local files or a NoSQL database (MongoDB).

    The main goal is to make sure the developer has structured logs. Instead of plain lines of text, the class turns each event into a rich data object, making audits and error hunting in production environments easier.

    #Execution Flow

    To understand how the class operates, picture the following path taken by a piece of information:

    1. Call to the log() Method: The user sends the message, the level (INFO, ERROR, etc.) and metadata.
    2. Configuration Resolution: The engine checks whether it should follow the class's global configuration or whether there was a specific instruction for that call (e.g. forcing the save to MongoDB only for a critical error).
    3. Payload Construction: The raw data is sent to a "Builder" that standardizes the format (adds timestamps, unique IDs and formats the JSON).
    4. Logger Configuration: The class prepares the "Handlers" (outputs). If save_logs is True, it opens a channel to the file; if it is going to show on the console, it sets the verbosity level.
    5. Emission and Persistence: The message is shown on screen and, at the same time, the structured payload is sent to MongoDB.

    #Methods Summary

    MethodResponsibility
    _get_env_boolReads environment variables (OS) and safely converts them to boolean.
    _resolve_configDecides which flags (save, show, persist) will be used in the current execution.
    _build_payloadsTurns the arguments into friendly messages and structured JSON objects.
    _get_loggerConfigures Python's native logging library (Handlers and Formatters).
    _emit_logPerforms the final dispatch of the message to the text outputs.
    _save_to_mongoManages the communication and insertion of the logs into the database.
    logSingle entry point. Orchestrates the execution of all the methods above.

    #Architecture and Insights

    • Hybrid Configuration: The class uses a priority pattern: Variável de Ambiente > Argumento do Método > Valor Padrão da Instância. This allows changing the log behavior without changing the code, just by changing the environment.
    • Payload Decoupling: Note that the class distinguishes the "text message" (for humans to read on the console) from the "data payload" (for machines to process in MongoDB).
    • Unique Traceability: Using an automatically generated log_id lets you trace a specific transaction across multiple files or database collections.

    #Technical Details

    #LoggerEngine Class

    Description
    Centralized manager of structured logs. Allows dynamic control of verbosity and data persistence in multiple destinations, ensuring standardization across the whole application.

    Arguments

    • log_id (str): Unique identifier of the transaction.
    • flag (str): Identifier of the origin (e.g. "AuthService").
    • file_name (str): Name of the originating Python module.
    • log_file_name (str): Prefix of the local log file.
    • show_info_logs (bool): Enables/Disables the INFO level on the console.
    • show_metadata (bool): Defines whether extra data appears in the log text.
    • save_logs (bool): Enables writing to a .log file.
    • save_mongo (bool): Enables persistence in MongoDB.
    • format_metadata (bool): Applies visual formatting to the metadata.

    #1. log() Method

    Description
    Main, public method. It acts as the class's "conductor", receiving the data and triggering the private methods in the correct order to process the log.

    Arguments

    • level (str): Severity level (e.g. "INFO", "WARNING", "ERROR", "CRITICAL").
    • func_name (str, optional): Name of the function where the log was generated.
    • message (str, optional): Explanatory text of the event.
    • metadata (dict, optional): Dictionary with additional technical data.
    • save_logs / save_mongo / show_info_logs / show_metadata (bool, optional): Parameters to override the instance's default behavior for this log only.

    Returns

    • dict: Returns the complete payload that was generated and/or persisted.

    Raises

    • AttributeError: If the given level is not a valid log level.
    • ConnectionError: If saving to MongoDB fails.

    Examples

    logger = LoggerEngine(flag="API_GATEWAY", save_mongo=True)

# Exemplo simples
logger.log(level="INFO", message="Servidor iniciado na porta 8080")

# Exemplo complexo com metadados e sobrescrita
logger.log(
    level="ERROR",
    func_name="process_payment",
    message="Falha na transação",
    metadata={"user_id": 123, "error_code": "ST-404"},
    save_logs=True # Força salvar em arquivo este erro específico
)

    #2. _get_env_bool() Method

    Description
    Internal utility to safely capture operating system settings, treating strings such as "true", "1" or "yes" as true boolean values.

    Arguments

    • env_name (str): The name of the environment variable key.
    • default (bool): The return value if the variable is not defined.

    Returns

    • bool: The resolved logical state.

    Raises

    • KeyError: If the value present in the environment variable is invalid (not convertible to boolean).

    Examples

    # Se no terminal: export SHOW_INFO_LOGS=True
val = engine._get_env_bool("SHOW_INFO_LOGS", False)
# val será True

    #3. _resolve_config() Method

    Description
    This method acts as the decision-making brain of the class. It compares the global settings (defined when instantiating the class) with the local settings (passed at log time). If a parameter is sent as None, it takes the instance default.

    Arguments

    • save_logs (bool/None): Wish to save to a file for this event.
    • save_mongo (bool/None): Wish to persist to the database for this event.
    • show_info_logs (bool/None): Wish to show the INFO level on the console.
    • show_metadata (bool/None): Wish to show metadata on the console.

    Returns

    • dict: A dictionary with the keys and their final boolean values (e.g. {'save_logs': True, ...}).

    Examples

    # Instância configurada para NÃO salvar nada
engine = LoggerEngine(save_logs=False)

# Chamada forçando o salvamento
config = engine._resolve_config(save_logs=True, save_mongo=None, ...)
# config['save_logs'] será True (sobrescrita)

    #4. _build_payloads() Method

    Description
    Responsible for standardizing the data. It separates the "message for humans" (formatted string) from the "payload for machines" (structured dictionary). It internally uses a helper class (PayloadBuilder) to ensure that all of the system's logs look the same.

    Arguments

    • level (str): Log level.
    • func_name (str): Name of the originating function.
    • message (str): Message text.
    • metadata (dict): Extra data.
    • show_metadata (bool): Defines whether the metadata dictionary should be injected into the text string.

    Returns

    • tuple: (display_message: str, mongo_payload: dict)

    #5. _get_logger() Method

    Description
    Configures the Python Standard Library infrastructure (logging). It creates the object that actually "talks" to the console and the file system, defining colors, date formats and which file the text should be sent to.

    Arguments

    • save_logs (bool): If True, adds a FileHandler.
    • show_info_logs (bool): Sets the logger's minimum level (DEBUG, INFO or WARNING).

    Returns

    • logging.Logger: The logger object ready to use.

    #6. _emit_log() Method

    Description
    It is the final trigger. Once everything is configured and the message is formatted, this method identifies the requested level (info, error, debug) and fires the command at the logger object.

    Arguments

    • logger (logging.Logger): The instance configured in the previous method.
    • level (str): The severity.
    • message (str): The final, already formatted message.

    Raises

    • AttributeError: If you try to use a level that does not exist (e.g. logger.log(level="BATATA")).

    #7. _save_to_mongo() Method

    Description
    Performs persistent persistence. It takes the structured payload and sends it to a collection in MongoDB. This is crucial for future dashboards (such as Grafana or Kibana).

    Arguments

    • mongo_metadata (dict): The complete payload generated by _build_payloads.

    Returns

    • str: The ID of the document inserted into the database.

    Raises

    • ConnectionError: If the database is down or the credentials are incorrect.

    #Log Lifecycle Summary

    To visualize how these methods interact, picture this sequence:

    1. User calls log().
    2. log() calls _resolve_config() to learn the rules.
    3. log() calls _build_payloads() to prepare the data.
    4. log() calls _get_logger() to prepare the output.
    5. log() calls _emit_log() to print to the screen/file.
    6. log() calls _save_to_mongo() to store it in the database.

    Source: src/tracing/logger_engine.py

    Esc
    ↑↓navigate Enteropen