Tracing Core

#Overview

The ApplicationTracing class acts as a Facade for log management. Instead of dealing directly with complex libraries or low-level settings, the developer uses this class to standardize how messages are recorded, displayed and stored.

The main goal is to ensure that all of the application's logs follow the same structure, making it easier to look for failures (troubleshooting) and to analyze data in tools such as MongoDB or log file viewers.

#Execution Flow

The class's workflow follows these stages:

1. Instantiation: The developer creates the object defining the global settings (e.g. whether to save to MongoDB, whether to show metadata on the console).
2. Encapsulation: The constructor internally initializes the LoggerEngine, which is the real processing engine.
3. Method Call: When calling a method such as .INFO() or .ERROR(), the parameters passed (message, metadata) are sent to the engine.
4. Dynamic Override: Each log method allows overriding the global settings momentarily (e.g. the system does not save INFO logs by default, but you can force a specific log to be saved).
5. Multi-channel Output: The log is processed and sent simultaneously to the console, local file or database, as configured.

#Methods Table

#Architecture and Insights

• Separation of Concerns: The class does not know how to write to MongoDB; it just delegates that responsibility to the LoggerEngine. This makes future maintenance easier.
• Granular Flexibility: The design lets you have a global behavior, but full flexibility on every line of code through the optional arguments of the methods.
• Structured Observability: Using the metadata argument (dictionary) encourages structured logging (JSON), which is much easier to index and search than plain text strings.
• Traceability: The log_id parameter makes it possible to correlate logs from the same transaction that crosses different functions or files.

#Technical Documentation

#ApplicationTracing Class

#Description

Class responsible for abstracting and standardizing the use of logs within the application. It encapsulates the complex logging logic and provides a simplified interface for the developer.

#Constructor Arguments

• log_id (str): Unique ID for flow tracking.
• flag (str): Marker to categorize logs.
• file_name (str): Context of the originating file.
• log_file_name (str): Name of the destination .log file.
• show_info_logs (bool): Enables/Disables INFO level logs on the console.
• show_metadata (bool): Defines whether technical details appear on the console.
• save_logs (bool): If True, writes to a physical file.
• save_mongo (bool): If True, persists to the database.
• format_metadata (bool): Applies visual formatting to the metadata.

#Methods

#1. INFO / DEBUG / WARNING / ERROR / CRITICAL

(The methods share the same signature to keep things consistent)

Description

Record a message at the corresponding severity level, handling storage and display according to the rules defined on the instance.

Arguments

• func_name (Optional[str]): Name of the function where the event occurred.
• message (Optional[str]): Explanatory text of the log.
• metadata (Optional[Dict]): Dictionary with extra data (e.g. {"user_id": 123}).
• save_logs (Optional[bool]): Overrides the global setting for saving to a file.
• save_mongo (Optional[bool]): Overrides the global setting for saving to MongoDB.
• show_info_logs (Optional[bool]): Forces INFO logs to be shown or hidden.
• show_metadata (Optional[bool]): Forces metadata to be shown or hidden.

Returns

• None: The method performs the recording (side effect) and returns no data.

Raises

• Exception: May propagate database connection errors or disk write permission errors originating in the LoggerEngine.

Examples

from src.tracing.tracing_core import ApplicationTracing

# Inicialização
tracer = ApplicationTracing(save_logs=True, log_id="TR-9952")

# Uso simples
tracer.INFO(
    func_name="create_user",
    message="App Init"
)

tracer.DEBUG(
    func_name="create_user",
    message="User created",
    metadata={"user": "Enzo"},
    #save_logs=False
    #show_metadata=False
)

tracer.WARNING(
    func_name="create_user",
    message="User created",
    metadata={"user": "Enzo"},
)

tracer.ERROR(
    func_name="create_user",
    message="User created",
    metadata={"user": "Enzo"},
)

tracer.CRITICAL(
    func_name="create_user",
    message="User created",
    metadata={"user": "Enzo"},
)

# Debug forçando salvamento no Mongo apenas para esta linha
tracer.DEBUG(message="Checkpont técnico", save_mongo=True)