NAME

Kernel::System::Log – Global log interface for managing and logging system messages.

SYNOPSIS

This module provides a global interface for logging messages at various severity levels such as debug, info, notice, and error. It integrates with Log4perl for logging and provides additional functionality for printing, handling shared memory, and working with Redis for log storage.

    use Kernel::System::ObjectManager;
    local $Kernel::OM = Kernel::System::ObjectManager->new(
        'Kernel::System::Log' => {
            LogPrefix => 'InstallScriptX',  # Optional but recommended
        },
    );
    my $LogObject = $Kernel::OM->Get('Kernel::System::Log');

    # Log a message
    $LogObject->Log(
        Priority => 'error',
        Message  => "An error occurred!",
    );

DESCRIPTION

Kernel::System::Log provides the ability to log messages at different levels (debug, info, notice, and error). It integrates with Log4perl for backend management and includes support for printing to standard output and standard error. The module also provides functionality to handle logs with shared memory (IPC) or Redis if configured.

METHODS

new()

Creates a new Kernel::System::Log object.

Do not instantiate this class directly; instead, use the object manager:

    local $Kernel::OM = Kernel::System::ObjectManager->new(
        'Kernel::System::Log' => { ... }
    );

    my $LogObject = $Kernel::OM->Get('Kernel::System::Log');

Parameters

LogPrefix – Optional log prefix, recommended for distinguishing log entries.
MinimumLogLevel – Optional log level; defaults to 'debug'.
Verbosity – Optional verbosity level; defaults to 'debug'.

InitPrinter()

Initializes the printer for printing messages to STDOUT or STDERR. Configures settings for colors, time format, and whether to print in raw or JSON format.

    $LogObject->InitPrinter(
        JSON      => 1,          # Optional, print in JSON format
        AddTime   => 1,          # Optional, add timestamp to logs
        PrintRaw  => 1,          # Optional, print raw messages
        Format    => 'json',     # Optional, specify format (raw|json)
        ANSI      => 1,          # Optional, enable ANSI colors
        Debug     => 1,          # Optional, enable debug logging
    );

Parameters

JSON – Whether to output logs in JSON format.
AddTime – Whether to add a timestamp to the log entries.
Format – Specify format (raw or json).
ANSI – Enable ANSI color output.
Debug – Enable debug level logging.

Log()

Logs a message. The supported priority levels are: debug, info, notice, and error.

    $LogObject->Log(
        Priority => 'error',  # debug|info|notice|error
        Message  => 'Need UserID!',
    );

Parameters

Priority – The priority level for the log message (error, notice, info, debug).

debug

Debug-level messages; info useful for debugging the application, not useful during operations.

info

Informational messages; normal operational messages – may be used for reporting etc, no action required.

notice

Normal but significant condition; events that are unusual but not error conditions, no immediate action required.

error

Error conditions. Non-urgent failures, should be relayed to developers or administrators, each item must be resolved.
Message – The message to log.
Caller – Optional, to specify the stack frame for logging.

    $LogObject->Log(
        Priority => 'error',
        Message  => "Need something!",
    );

ANSI()

Enable or disable ANSI color support for log messages.

    $LogObject->ANSI(1);   # Enable ANSI color
    $LogObject->ANSI(0);   # Disable ANSI color

Verbosity()

Set Minimum Log Level of Screen Printer.

By default it contains the value of the Log::Print::Verbosity setting.

It could have been overridden by the constructor new() or the InitPrinter() method.

    $LogObject->Verbosity('error');   # Lowest Verbosity
    $LogObject->Verbosity('debug');   # Highest Verbosity

LogLevel()

Set Minimum Log Level of global Logger.

By default it contains the value of the MinimumLogLevel setting.

It could have been overridden by the constructor new().

    $LogObject->LogLevel('error');   # Lowest Log Level (only log errors)
    $LogObject->LogLevel('debug');   # Highest Log Level (log debug messages)

Print()

Prints a log message to STDOUT. Supports adding colors and timestamps.

    $LogObject->Print(
        Text | Message  => 'This is a log message',
        Priority        => 'info',                  # Optional, default is 'info'
        Module          => 'MyModule',              # Optional, name of the calling module
    );

PrintError()

Prints a log message to STDERR. Supports adding colors and timestamps.

You can add color tags (<green>...</green>, <yellow>...</yellow>, <red>...</red>) to your text, and they will be replaced with the corresponding terminal escape sequences if the terminal supports it.

    $LogObject->PrintError(
        Text | Message  => 'This is an error message',
        Priority        => 'error',     # Optional, default is 'error'
        Module          => 'MyModule',  # Optional, name of the calling module
    );

_Format()

Formats a log message for output, including adding colors or timestamps based on configuration.

_Color()

Adds ANSI color to the given text, if ANSI output is enabled.

this will color the given text (see Term::ANSIColor::color()) if ANSI output is available and active, otherwise the text stays unchanged.

    my $ColoredText = $LogObject->_Color('green', $Text);

_ReplaceColorTags()

Replaces color tags in the format <green>...</green> with ANSI color escape sequences.

_RemoveColorTags()

Removes color tags like <green>...</green> from text.

_TrimText()

Trims leading and trailing whitespace from a text string.

GetLogEntry()

Retrieve the last log entry for a specific priority and type.

    my $LastErrorMessage = $LogObject->GetLogEntry(
        Type => 'error',        # error|info|notice
        What => 'Message',      # Message|Traceback
    );

Parameters

Type – The log priority to retrieve (error, info, notice).
What – The log detail to retrieve (Message, Traceback).

GetLog()

Retrieve all logs currently stored in shared memory or Redis (depending on configuration).

    my $AllLogs = $LogObject->GetLog();

CleanUp()

Cleans up the shared memory or Redis storage used for logs.

    $LogObject->CleanUp();

Dumper()

Logs a Perl data structure using Data::Dumper.

    $LogObject->Dumper(@Array);

    or

    $LogObject->Dumper(%Hash);

AUTHOR

This module was created by the OTRS development team The Awesome – Team B -.

Truncate()

Transverse a data structure and truncate every value if it exceeds a certain size threshold.

    my $TruncatedData = $LogObject->Truncate(
        Data      => $DataStructure,
        Threshold => 1000,                 # Defaults to 10_000
    );

Facebook X LinkedIn