/ 
glog-1.0.5-3
/ glog

NAME

glog - Simple, Fast Functional Logging Interface

SYNOPSIS

use glog;

# Set log level
LogLevel(5);  # Enable debug logging

# Log messages
LogInfo("Application started");
LogDebug("Debug details: x=42");
LogWarn("Warning: low disk space");
LogErr("Error: cannot open file");
LogDie("Fatal error!");

# Formatted logging
LogF(3, "User %s logged in at %d", "alice", time);

# Log to a file
LogFile("app.log");
LogInfo("Logging to file");
LogFile(undef);  # Revert to STDERR

DESCRIPTION

glog is a lightweight, Pure Perl functional logging interface. It serves as a simple, high-level proxy to the underlying glog::logger module, providing a drop-in solution for logging messages at various severity levels (ERROR, WARN, INFO, DEBUG). The module is optimized for minimal overhead, making it suitable for both small scripts and large-scale systems.

glog delegates all logging operations to a global glog::logger instance, ensuring consistency and ease of use. It exports a set of intuitive functions that allow developers to log messages without managing logger objects directly. The module is designed to provide robust, dependency-free utilities for Perl developers.

EXPORTED FUNCTIONS

The following functions are exported by default via @EXPORT:

  • LogLevel($level)

    Sets or retrieves the current log level (0-9). If $level is provided, it updates the log level; otherwise, it returns the current level. The default level is 3 (INFO).

    LogLevel(5);  # Enable DEBUG logging
my $current = LogLevel();  # Get current level

  • Log($level, $message)

    Logs a message at the specified level if it is less than or equal to the current log level. The message is prefixed with a timestamp and level name.

    Log(3, "Processing started");

  • LogFormat($level, $format, @args)

    Logs a formatted message (using sprintf) at the specified level if allowed by the current log level.

    LogFormat(3, "Processed %d items in %s", 42, "2s");

  • LogF($level, $format, @args)

    An alias for LogFormat, provided for convenience.

    LogF(3, "User %s logged in", "bob");

  • LogFile($path)

    Configures logging to a file. If $path is provided, logs are appended to the specified file. If undef is passed, logging reverts to STDERR.

    LogFile("app.log");  # Log to app.log
LogFile(undef);      # Revert to STDERR

  • LogDie($message)

    Logs an ERROR message (level 1) and terminates the program with die.

    LogDie("Cannot connect to database");

  • LogWarn($message)

    Logs a WARN message (level 2).

    LogWarn("Configuration file not found, using defaults");

  • LogInfo($message)

    Logs an INFO message (level 3).

    LogInfo("Server started on port 8080");

  • LogDebug($message)

    Logs a DEBUG message (level 5).

    LogDebug("Variable x = 42");

  • LogErr($message)

    Logs an ERROR message (level 1) without terminating the program.

    LogErr("Failed to read input file");

LOG LEVELS

The module supports the following log levels:

  • 1: ERROR (critical errors)

  • 2: WARN (warnings)

  • 3: INFO (informational messages)

  • 5: DEBUG (detailed debugging information)

Messages are only logged if their level is less than or equal to the current log level set by LogLevel. For example, setting LogLevel(2) will log ERROR and WARN messages but ignore INFO and DEBUG.

OUTPUT FORMAT

Log messages follow a consistent format:

[YYYY-MM-DD HH:MM:SS.mmm] LEVEL message

Example output:

[2025-04-25 20:15:23.456] INFO Application started
[2025-04-25 20:15:23.789] ERROR Cannot open file

The timestamp includes millisecond precision, generated using Time::HiRes.

PERFORMANCE OPTIMIZATIONS

glog is designed for minimal overhead:

  • **Proxy Design**: All logic is delegated to glog::logger, reducing code duplication and ensuring fast function calls.

  • **Level Checks**: Logging is skipped early if the message level exceeds the current log level.

  • **Global Instance**: Uses a single glog::logger instance to avoid object creation overhead.

  • **Pure Perl**: No external dependencies, ensuring portability and fast execution.

TESTING

The internal _test function validates:

  • Logging at all levels (ERROR, WARN, INFO, DEBUG).

  • Formatted logging with LogF.

  • File-based logging with LogFile.

  • Error handling with LogDie.

To run the tests, use a test script that calls glog::_test. The test suite captures and verifies log output, ensuring correct formatting and behavior.

Example test usage:

use Test::More;
ok(glog->_test, "glog internal tests passed");
done_testing();

LIMITATIONS

  • Relies on a single global glog::logger instance, which may not be suitable for applications requiring multiple logger configurations.

  • No built-in log rotation or advanced file management.

  • No native threading support; use caution in multi-threaded environments.

DEPENDENCIES

  • glog::loggerr (required for all logging operations)

  • strict, warnings, Exporter (standard Perl modules)

No external CPAN dependencies are required, keeping the module lightweight and portable.

INTEGRATION WITH DOMERO TOOLS

glog is designed to integrate seamlessly with other modules. It provides a consistent logging interface for debugging and monitoring, making it ideal for applications.

Example with G::CRC:

use glog;
use gcrc;

LogLevel(5);  # Enable debug
my $crc = enc_crc32("Hello World");
LogInfo("Computed CRC32: $crc");
LogDebug("Validating CRC32...");
valid_crc32("Hello World", $crc) or LogDie("CRC mismatch");

AUTHOR

OnEhIppY <domerosoftware@gmail.com>, Domero Software

SEE ALSO

  • glog::logger - The underlying object-oriented logging implementation.

VERSION

1.0.5

LICENSE

This module is distributed under the MIT License. See the LICENSE file in the distribution for details.