Complete API Reference¶

Comprehensive professional reference for all Logly functionality with detailed tables, examples, and best practices.

Overview¶

Logly is a high-performance Rust-powered Python logging library providing structured logging, async I/O, rotation, filtering, and extensive configuration options. This reference covers all 40+ methods available in the global logger instance.

Logger Instance¶

Import the global logger instance:

from logly import logger

All examples in this reference use this import pattern.

Configuration Methods¶

logger.configure()¶

Configure global logger settings including level, output format, colors, and display options.

Signature¶

logger.configure(
    level: str = "INFO",
    color: bool = True,
    level_colors: dict[str, str] | None = None,
    json: bool = False,
    pretty_json: bool = False,
    console: bool = True,
    show_time: bool = True,
    show_module: bool = True,
    show_function: bool = True,
    show_filename: bool = False,
    show_lineno: bool = False,
    console_levels: dict[str, bool] | None = None,
    time_levels: dict[str, bool] | None = None,
    color_levels: dict[str, bool] | None = None,
    storage_levels: dict[str, bool] | None = None,
    color_callback: callable | None = None,
    auto_sink: bool = True
) -> None

Parameters Table¶

Returns¶

• Type: None
• Description: Configuration is applied globally to all subsequent log calls.

Examples¶

from logly import logger

logger.configure(level="INFO", color=True, show_time=True)
logger.add("console")

logger.info("Application started", version="1.0.0")
logger.error("Connection failed", retry=3)

2025-01-15 14:30:45 | INFO     | __main__:main:4 - Application started version=1.0.0
2025-01-15 14:30:46 | ERROR    | __main__:main:5 - Connection failed retry=3

from logly import logger

logger.configure(level="INFO", json=True, pretty_json=False)
logger.add("console")

logger.info("User login", user="alice", ip="192.168.1.1")

{"timestamp":"2025-01-15T14:30:45.123Z","level":"INFO","module":"__main__","function":"main","message":"User login","user":"alice","ip":"192.168.1.1"}

from logly import logger

logger.configure(level="DEBUG", json=True, pretty_json=True)
logger.add("console")

logger.debug("Processing request", request_id="abc123", step=1)

{
  "timestamp": "2025-01-15T14:30:45.123Z",
  "level": "DEBUG",
  "module": "__main__",
  "function": "main",
  "message": "Processing request",
  "request_id": "abc123",
  "step": 1
}

from logly import logger

custom_colors = {
    "INFO": "32",      # Green
    "WARNING": "33",   # Yellow
    "ERROR": "91",     # Bright Red
    "CRITICAL": "95"   # Bright Magenta
}

logger.configure(level="INFO", color=True, level_colors=custom_colors)
logger.add("console")

logger.info("Success")
logger.warning("Warning")
logger.error("Error")

2025-01-15 14:30:45 | INFO     | __main__:main:12 - Success          (in green)
2025-01-15 14:30:46 | WARNING  | __main__:main:13 - Warning          (in yellow)
2025-01-15 14:30:47 | ERROR    | __main__:main:14 - Error            (in bright red)

from logly import logger

custom_colors = {
    "INFO": "GREEN",
    "WARNING": "YELLOW",
    "ERROR": "RED",
    "CRITICAL": "BRIGHT_MAGENTA"
}

logger.configure(level="INFO", color=True, level_colors=custom_colors)
logger.add("console")

logger.info("Green message")
logger.warning("Yellow message")
logger.error("Red message")

2025-01-15 14:30:45 | INFO     | __main__:main:12 - Green message     (in green)
2025-01-15 14:30:46 | WARNING  | __main__:main:13 - Yellow message    (in yellow)
2025-01-15 14:30:47 | ERROR    | __main__:main:14 - Red message       (in red)

from logly import logger

logger.configure(
    level="DEBUG",
    console_levels={"DEBUG": False},  # Hide DEBUG from console
    time_levels={"ERROR": True, "INFO": False},  # Time only for errors
    storage_levels={"TRACE": False}  # Don't store TRACE in files
)
logger.add("console")
logger.add("app.log")

logger.debug("Debug message")  # To file only
logger.info("Info message")    # To console and file, no time
logger.error("Error message")  # To console and file, with time

INFO     | __main__:main:13 - Info message
2025-01-15 14:30:46 | ERROR    | __main__:main:14 - Error message

DEBUG    | __main__:main:12 - Debug message
INFO     | __main__:main:13 - Info message
2025-01-15 14:30:46 | ERROR    | __main__:main:14 - Error message

from logly import logger

def custom_color(level, text):
    """Custom color function using ANSI codes."""
    colors = {
        "DEBUG": "\033[36m",    # Cyan
        "INFO": "\033[32m",     # Green
        "WARNING": "\033[33m",  # Yellow
        "ERROR": "\033[31m",    # Red
        "CRITICAL": "\033[35m"  # Magenta
    }
    reset = "\033[0m"
    color_code = colors.get(level, "")
    return f"{color_code}{text}{reset}"

logger.configure(level="DEBUG", color_callback=custom_color)
logger.add("console")

logger.debug("Custom colored debug")
logger.info("Custom colored info")
logger.error("Custom colored error")

2025-01-15 14:30:45 | DEBUG    | __main__:main:18 - Custom colored debug    (in cyan)
2025-01-15 14:30:46 | INFO     | __main__:main:19 - Custom colored info     (in green)
2025-01-15 14:30:47 | ERROR    | __main__:main:20 - Custom colored error    (in red)

Available Color Codes¶

Do's and Don'ts¶

✅ DO: - Call configure() once at application startup - Use "INFO" or "WARNING" level in production - Use "DEBUG" level during development - Use json=True for log aggregation (ELK, Splunk) - Use pretty_json=True only in development - Use per-level controls for fine-grained output

❌ DON'T: - Call configure() multiple times (creates inconsistency) - Use "TRACE" level in production (too verbose) - Use pretty_json=True in production (performance cost) - Disable console in development (hard to debug) - Forget to add sinks after configuring

logger.reset()¶

Reset logger configuration to default settings.

Signature¶

logger.reset() -> None

Parameters¶

None

Returns¶

• Type: None
• Description: All settings return to default values. Clears per-level controls and custom configurations.

Examples¶

from logly import logger

# Custom configuration
logger.configure(level="DEBUG", json=True, show_time=False)
logger.info("Custom config")

# Reset to defaults
logger.reset()
logger.info("Default config")

{"level":"INFO","message":"Custom config"}

2025-01-15 14:30:45 | INFO     | __main__:main:9 - Default config

import pytest
from logly import logger

@pytest.fixture(autouse=True)
def reset_logger():
    yield
    logger.reset()  # Clean state for next test

Use Cases¶

• 🧪 Testing: Clean state between tests
• 🔄 Reconfiguration: Reset before applying new config
• 🐛 Debugging: Return to known default state

Do's and Don'ts¶

✅ DO: - Use in test teardown for clean state - Reset before major reconfiguration - Document when reset is called

❌ DON'T: - Reset in production without reconfiguring - Reset during active logging - Assume sinks are removed (reset only affects config)

Sink Management Methods¶

logger.add()¶

Add a logging sink (output destination) with optional rotation, filtering, and async writing.

Signature¶

logger.add(
    sink: str | None = None,
    rotation: str | None = None,
    size_limit: str | None = None,
    retention: int | None = None,
    filter_min_level: str | None = None,
    filter_module: str | None = None,
    filter_function: str | None = None,
    async_write: bool = True,
    buffer_size: int = 8192,
    flush_interval: int = 100,
    max_buffered_lines: int = 1000,
    date_style: str | None = None,
    date_enabled: bool = False,
    format: str | None = None,
    json: bool = False
) -> int

Parameters Table¶

Returns¶

• Type: int
• Description: Handler ID for this sink. Use with remove(), read(), delete(), etc.

Examples¶

See Sink Management API for 20+ detailed examples with outputs.

Quick Examples:

from logly import logger

# Console sink
logger.add("console")

# File with daily rotation
id1 = logger.add("app.log", rotation="daily", retention=7)

# Error-only sink
id2 = logger.add("errors.log", filter_min_level="ERROR")

# JSON sink
id3 = logger.add("data.log", json=True, async_write=True)

# Custom format
id4 = logger.add("custom.log", format="{time} [{level}] {message}")

logger.info("Test message", user="alice")

Explanation: Demonstrates adding multiple sinks with different purposes: console for development, rotating file for general logs, error-only file for critical issues, JSON file for structured data, and custom format file for specific needs.

Expected Output (console):

2025-01-15 14:30:45 | INFO     | __main__:main:15 - Test message user=alice

Expected Output (app.log, errors.log, data.log, custom.log): Each file receives the log according to its configuration. See Sink Management API for detailed outputs.

Do's and Don'ts¶

✅ DO: - Use multiple sinks for different purposes - Enable async_write=True for high throughput - Set retention to manage disk space - Use filter_min_level to reduce noise - Store handler IDs for later removal

❌ DON'T: - Create too many sinks (> 20) - Use async_write=False without good reason - Forget to set retention on production logs - Hardcode file paths (use config files)

logger.remove()¶

Remove a logging sink by handler ID.

Signature¶

logger.remove(handler_id: int) -> bool

Parameters Table¶

Returns¶

• Type: bool
• Description: True if removed successfully, False if ID not found.

Example¶

from logly import logger

handler = logger.add("temp.log")
logger.info("Temporary message")

success = logger.remove(handler)
print(f"Removed: {success}")  # True

logger.info("This won't go to temp.log")

Explanation: Creates a temporary sink, logs a message, then removes the sink. Subsequent logs won't be written to that sink. Returns True if removal was successful.

Expected Output:

Removed: True

logger.remove_all()¶

Remove all logging sinks.

Signature¶

logger.remove_all() -> int

Returns¶

• Type: int
• Description: Number of sinks removed.

Example¶

from logly import logger

logger.add("app.log")
logger.add("error.log")
logger.add("console")

count = logger.remove_all()
print(f"Removed {count} sinks")  # 3

logger.info("This log goes nowhere")

Explanation: Removes all active sinks at once. Returns the count of sinks removed. After removal, logs are discarded until new sinks are added. Useful for cleanup or reconfiguration.

Expected Output:

Removed 3 sinks

logger.sink_count()¶

Get number of active sinks.

Signature¶

logger.sink_count() -> int

Returns¶

• Type: int
• Description: Total number of active sinks.

Example¶

from logly import logger

logger.add("app.log")
logger.add("error.log")
logger.add("console")

count = logger.sink_count()
print(f"Active sinks: {count}")  # 3

logger.remove_all()
count = logger.sink_count()
print(f"Active sinks: {count}")  # 0

Explanation: Returns the number of currently active sinks. Useful for debugging configuration or ensuring expected number of outputs. Changes dynamically as sinks are added or removed.

Expected Output:

Active sinks: 3
Active sinks: 0

logger.list_sinks()¶

List all sink handler IDs.

Signature¶

logger.list_sinks() -> list[int]

Returns¶

• Type: list[int]
• Description: List of handler IDs for all active sinks.

Example¶

from logly import logger

id1 = logger.add("app.log")
id2 = logger.add("error.log")
id3 = logger.add("console")

ids = logger.list_sinks()
print(f"Sink IDs: {ids}")  # [1, 2, 3]

# Remove one sink
logger.remove(id2)
ids = logger.list_sinks()
print(f"Sink IDs: {ids}")  # [1, 3]

Explanation: Returns all handler IDs for active sinks. Useful for iterating over sinks, selective removal, or debugging. IDs are assigned sequentially starting from 1.

Expected Output:

Sink IDs: [1, 2, 3]
Sink IDs: [1, 3]

logger.sink_info()¶

Get detailed information about a specific sink.

Signature¶

logger.sink_info(handler_id: int) -> dict | None

Parameters Table¶

Returns¶

• Type: dict | None
• Description: Dictionary with sink configuration, or None if not found.

Response Fields Table¶

Example¶

from logly import logger

id = logger.add("app.log", rotation="daily", async_write=True)

info = logger.sink_info(id)
print(f"Path: {info['path']}")
print(f"Rotation: {info['rotation']}")
print(f"Async: {info['async_write']}")

Explanation: Returns a dictionary with all configuration details for a specific sink. Useful for debugging, auditing, or dynamically adjusting behavior based on sink configuration.

Expected Output:

Path: app.log
Rotation: daily
Async: True

logger.all_sinks_info()¶

Get information about all sinks.

Signature¶

logger.all_sinks_info() -> list[dict]

Returns¶

• Type: list[dict]
• Description: List of dictionaries with sink configurations (same format as sink_info()).

Example¶

from logly import logger

logger.add("app.log", rotation="daily")
logger.add("error.log", filter_min_level="ERROR", json=True)

for sink in logger.all_sinks_info():
    print(f"{sink['path']}: rotation={sink['rotation']}, json={sink['json']}")

Explanation: Returns a list of dictionaries, one for each sink, containing complete configuration. Perfect for logging system introspection or generating configuration reports.

Expected Output:

app.log: rotation=daily, json=False
error.log: rotation=None, json=True

File Operations Methods¶

logger.delete()¶

Delete log file for a specific sink (keeps sink active).

Signature¶

logger.delete(handler_id: int) -> bool

Parameters Table¶

Returns¶

• Type: bool
• Description: True if file deleted, False if failed or sink not found.

Example¶

from logly import logger

id = logger.add("app.log")
logger.info("Some logs")

success = logger.delete(id)  # Deletes file, sink remains
print(f"Deleted: {success}")  # True

logger.info("Creates new file")  # New app.log created

Explanation: Deletes the physical log file but keeps the sink configuration active. The next log message will create a fresh file. Useful for clearing old logs without reconfiguring sinks.

Expected Output:

Deleted: True

Behavior¶

• ✅ Deletes the log file
• ✅ Sink remains active
• ✅ Next log creates new file
• ❌ Does not remove sink configuration

logger.delete_all()¶

Delete all log files (keeps sinks active).

Signature¶

logger.delete_all() -> int

Returns¶

• Type: int
• Description: Number of files deleted.

Example¶

from logly import logger

logger.add("app.log")
logger.add("error.log")
logger.info("Logs")

count = logger.delete_all()
print(f"Deleted {count} files")  # 2

logger.info("Fresh start")  # Creates new files

Explanation: Deletes all log files while keeping sinks active. Useful for log rotation, testing, or starting fresh without reconfiguring. Sinks will create new files on next write.

Expected Output:

Deleted 2 files

logger.read()¶

Read log content from a sink's file.

Signature¶

logger.read(handler_id: int) -> str | None

Parameters Table¶

Returns¶

• Type: str | None
• Description: File contents as string, or None if file doesn't exist or sink not found.

Example¶

from logly import logger

id = logger.add("app.log")
logger.info("Message 1")
logger.info("Message 2")

content = logger.read(id)
print(content)

Explanation: Returns the entire content of a sink's log file as a string. Useful for programmatic log analysis, testing, or displaying logs in UI. Returns None if file doesn't exist.

Expected Output:

2025-01-15 14:30:45 | INFO     | __main__:main:4 - Message 1
2025-01-15 14:30:46 | INFO     | __main__:main:5 - Message 2

logger.read_all()¶

Read log content from all sinks.

Signature¶

logger.read_all() -> dict[int, str]

Returns¶

• Type: dict[int, str]
• Description: Dictionary mapping handler IDs to file contents.

Example¶

from logly import logger

id1 = logger.add("app.log")
id2 = logger.add("error.log", filter_min_level="ERROR")
logger.info("Info message")
logger.error("Error message")

all_logs = logger.read_all()
for sink_id, content in all_logs.items():
    print(f"Sink {sink_id}:\n{content}\n")

Explanation: Reads content from all sink files and returns a dictionary mapping handler IDs to file contents. Great for aggregating logs or exporting all logging data at once.

Expected Output:

Sink 1:
2025-01-15 14:30:45 | INFO     | __main__:main:5 - Info message
2025-01-15 14:30:46 | ERROR    | __main__:main:6 - Error message

Sink 2:
2025-01-15 14:30:46 | ERROR    | __main__:main:6 - Error message

logger.file_size()¶

Get file size in bytes.

Signature¶

logger.file_size(handler_id: int) -> int | None

Parameters Table¶

Returns¶

• Type: int | None
• Description: File size in bytes, or None if file doesn't exist.

Example¶

from logly import logger

id = logger.add("app.log")
logger.info("Hello world")

size = logger.file_size(id)
print(f"Log file is {size} bytes")

Explanation: Returns the file size in bytes. Useful for monitoring log growth, implementing custom rotation logic, or checking if logs are being written. Returns None if file doesn't exist.

Expected Output:

Log file is 78 bytes

logger.file_metadata()¶

Get detailed file metadata.

Signature¶

logger.file_metadata(handler_id: int) -> dict | None

Parameters Table¶

Returns¶

• Type: dict | None
• Description: Dictionary with metadata fields, or None if file doesn't exist.

Metadata Fields Table¶

Example¶

from logly import logger

id = logger.add("app.log")
logger.info("Test")

metadata = logger.file_metadata(id)
print(f"Size: {metadata['size']} bytes")
print(f"Created: {metadata['created']}")
print(f"Modified: {metadata['modified']}")
print(f"Path: {metadata['path']}")

Explanation: Returns comprehensive file metadata including size, timestamps, and absolute path. Perfect for monitoring, auditing, or displaying file information in dashboards.

Expected Output:

Size: 65 bytes
Created: 2025-01-15T14:30:45.123Z
Modified: 2025-01-15T14:30:45.456Z
Path: E:\Projects\logly\app.log

logger.read_lines()¶

Read specific lines from a log file.

Signature¶

logger.read_lines(handler_id: int, start: int, end: int) -> str | None

Parameters Table¶

Returns¶

• Type: str | None
• Description: Selected lines as string, or None if file doesn't exist.

Examples¶

from logly import logger

id = logger.add("app.log")
for i in range(20):
    logger.info(f"Message {i}")

# Read first 5 lines
lines = logger.read_lines(id, 1, 5)
print(lines)

2025-01-15 14:30:45 | INFO     | __main__:main:5 - Message 0
2025-01-15 14:30:45 | INFO     | __main__:main:5 - Message 1
2025-01-15 14:30:45 | INFO     | __main__:main:5 - Message 2
2025-01-15 14:30:45 | INFO     | __main__:main:5 - Message 3
2025-01-15 14:30:45 | INFO     | __main__:main:5 - Message 4

# Read last 3 lines
lines = logger.read_lines(id, -3, -1)
print(lines)

2025-01-15 14:30:46 | INFO     | __main__:main:5 - Message 17
2025-01-15 14:30:46 | INFO     | __main__:main:5 - Message 18
2025-01-15 14:30:46 | INFO     | __main__:main:5 - Message 19

# Read lines 10-15
lines = logger.read_lines(id, 10, 15)
print(lines)

logger.line_count()¶

Count lines in a log file.

Signature¶

logger.line_count(handler_id: int) -> int | None

Parameters Table¶

Returns¶

• Type: int | None
• Description: Number of lines in file, or None if file doesn't exist.

Example¶

from logly import logger

id = logger.add("app.log")
logger.info("Line 1")
logger.info("Line 2")
logger.info("Line 3")

count = logger.line_count(id)
print(f"Lines: {count}")  # 3

Explanation: Returns the total number of lines in the log file. Perfect for monitoring log volume, implementing pagination, or detecting unexpected log growth.

Expected Output:

Lines: 3

logger.read_json()¶

Read and parse JSON log file.

Signature¶

logger.read_json(handler_id: int, pretty: bool = False) -> str | None

Parameters Table¶

Returns¶

• Type: str | None
• Description: JSON-formatted string, or None if file doesn't exist.

Examples¶

from logly import logger

id = logger.add("app.log", json=True)
logger.info("Test", user="alice", action="login")

json_logs = logger.read_json(id)
print(json_logs)

{"timestamp":"2025-01-15T14:30:45.123Z","level":"INFO","module":"__main__","function":"main","message":"Test","user":"alice","action":"login"}

pretty_logs = logger.read_json(id, pretty=True)
print(pretty_logs)

{
  "timestamp": "2025-01-15T14:30:45.123Z",
  "level": "INFO",
  "module": "__main__",
  "function": "main",
  "message": "Test",
  "user": "alice",
  "action": "login"
}

logger.clear()¶

Clear console display.

Signature¶

logger.clear() -> None

Returns¶

• Type: None
• Description: Clears terminal screen (platform-specific).

Example¶

from logly import logger

logger.add("console")
logger.info("Message 1")
logger.info("Message 2")
logger.clear()  # Clears console
logger.info("Message 3")

Explanation: Clears the terminal screen using platform-specific commands (cls on Windows, clear on Unix). Useful for resetting console output during development or interactive sessions.

Expected Behavior: Console is cleared, then "Message 3" appears as the first visible log.

Platform Behavior¶

Logging Methods¶

logger.trace()¶

Log at TRACE level (most verbose).

Signature¶

logger.trace(message: str, *args, **kwargs) -> None

Parameters Table¶

Example¶

from logly import logger

logger.configure(level="TRACE")
logger.add("console")

logger.trace("Detailed trace", request_id="abc123", step=1)

Explanation: TRACE is the most verbose level, typically used for very detailed debugging. Requires configuring level to TRACE to see these logs.

Expected Output:

2025-01-15 14:30:45 | TRACE    | __main__:main:5 - Detailed trace request_id=abc123 step=1

Use Case: Very detailed debugging, function entry/exit, variable inspection.

logger.debug()¶

Log at DEBUG level.

Signature¶

logger.debug(message: str, *args, **kwargs) -> None

Parameters Table¶

Example¶

from logly import logger

logger.configure(level="DEBUG")
logger.add("console")

item_id = "item_42"
logger.debug("Processing item %s", item_id, user="alice", status="active")

Explanation: DEBUG level for development debugging. The %s placeholder is replaced with item_id value. Extra kwargs (user, status) are appended to the log.

Expected Output:

2025-01-15 14:30:45 | DEBUG    | __main__:main:6 - Processing item item_42 user=alice status=active

Use Case: Development debugging, state inspection, flow tracking.

logger.info()¶

Log at INFO level.

Signature¶

logger.info(message: str, *args, **kwargs) -> None

Parameters Table¶

Example¶

from logly import logger

logger.add("console")

logger.info("User logged in", user_id=42, ip="192.168.1.1")

Explanation: INFO level for general informational messages about normal operations. This is the default logging level for production.

Expected Output:

2025-01-15 14:30:45 | INFO     | __main__:main:5 - User logged in user_id=42 ip=192.168.1.1

Use Case: General information, normal operations, user actions.

logger.success()¶

Log at SUCCESS level.

Signature¶

logger.success(message: str, *args, **kwargs) -> None

Parameters Table¶

Example¶

from logly import logger

logger.add("console")

logger.success("Payment processed", amount=100.50, transaction_id="tx123")

Explanation: SUCCESS level is unique to Logly, sitting between INFO and WARNING. Perfect for highlighting successful operations that deserve special attention.

Expected Output:

2025-01-15 14:30:45 | SUCCESS  | __main__:main:5 - Payment processed amount=100.5 transaction_id=tx123

Use Case: Successful operations, completion notifications, positive outcomes.

logger.warning()¶

Log at WARNING level.

Signature¶

logger.warning(message: str, *args, **kwargs) -> None

Parameters Table¶

Example¶

from logly import logger

logger.add("console")

logger.warning("Rate limit approaching", current=95, limit=100)

Explanation: WARNING level indicates potential issues that don't prevent normal operation but should be reviewed. Often colored yellow/orange.

Expected Output:

2025-01-15 14:30:45 | WARNING  | __main__:main:5 - Rate limit approaching current=95 limit=100

Use Case: Warnings, deprecated features, recoverable issues.

logger.error()¶

Log at ERROR level.

Signature¶

logger.error(message: str, *args, **kwargs) -> None

Parameters Table¶

Example¶

from logly import logger

logger.add("console")

logger.error("Database connection failed", db="postgres", retry=3)

Explanation: ERROR level for failures and exceptions. Use this for errors that prevent specific operations but don't crash the entire system.

Expected Output:

2025-01-15 14:30:45 | ERROR    | __main__:main:5 - Database connection failed db=postgres retry=3

Use Case: Errors, failures, exceptions (without traceback).

logger.critical()¶

Log at CRITICAL level (most severe).

Signature¶

logger.critical(message: str, *args, **kwargs) -> None

Parameters Table¶

Example¶

from logly import logger

logger.add("console")

logger.critical("System shutdown", reason="out_of_memory")

Explanation: CRITICAL is the highest severity level for catastrophic failures that require immediate attention. Often triggers alerts in production.

Expected Output:

2025-01-15 14:30:45 | CRITICAL | __main__:main:5 - System shutdown reason=out_of_memory

Use Case: Critical failures, system shutdown, data corruption.

logger.log()¶

Log at custom or aliased level.

Signature¶

logger.log(level: str, message: str, *args, **kwargs) -> None

Parameters Table¶

Example¶

from logly import logger

logger.add("console")

# Create custom level alias
logger.level("NOTICE", "INFO")

# Use custom level
logger.log("NOTICE", "Custom message", priority=5)

Explanation: The log() method allows logging at custom or aliased levels. Here, NOTICE is aliased to INFO level, so it has INFO's severity but displays as NOTICE.

Expected Output:

2025-01-15 14:30:45 | NOTICE   | __main__:main:8 - Custom message priority=5

Log Level Hierarchy¶

Filtering: When filter_min_level="INFO", logs at INFO, SUCCESS, WARNING, ERROR, and CRITICAL are included. TRACE and DEBUG are excluded.

Context Management Methods¶

logger.bind()¶

Create logger with bound context fields.

Signature¶

logger.bind(**kwargs) -> LoggerProxy

Parameters Table¶

Returns¶

• Type: LoggerProxy
• Description: New logger instance with bound context. All logs include these fields.

Examples¶

from logly import logger

logger.add("console")

# Create request-scoped logger
request_logger = logger.bind(request_id="abc123", user="alice")

request_logger.info("Processing request")
request_logger.info("Validating data")
request_logger.info("Request complete")

2025-01-15 14:30:45 | INFO     | __main__:main:7 - Processing request request_id=abc123 user=alice
2025-01-15 14:30:46 | INFO     | __main__:main:8 - Validating data request_id=abc123 user=alice
2025-01-15 14:30:47 | INFO     | __main__:main:9 - Request complete request_id=abc123 user=alice

# Service-level logger
payment_logger = logger.bind(service="payment", version="2.0")

payment_logger.info("Payment initiated", amount=100.50)
payment_logger.success("Payment completed", transaction="tx123")

2025-01-15 14:30:45 | INFO     | __main__:main:4 - Payment initiated service=payment version=2.0 amount=100.5
2025-01-15 14:30:46 | SUCCESS  | __main__:main:5 - Payment completed service=payment version=2.0 transaction=tx123

# Create nested context
app_logger = logger.bind(app="myapp", env="production")
auth_logger = app_logger.bind(component="auth")

auth_logger.info("User login")
# Output: INFO: User login app=myapp env=production component=auth

2025-01-15 14:30:45 | INFO     | __main__:main:5 - User login app=myapp env=production component=auth

Use Cases¶

• 🌐 Request Tracking: Bind request ID, user, session
• 🏗️ Component Context: Bind service name, version
• 👤 User Context: Bind user ID, role, tenant
• 🔧 Environment Context: Bind environment, region, instance

logger.contextualize()¶

Temporarily attach context fields (context manager).

Signature¶

logger.contextualize(**kwargs)

Parameters Table¶

Returns¶

• Type: Context manager
• Description: Context fields active only within with block.

Examples¶

from logly import logger

logger.add("console")

logger.info("Before")  # No context

with logger.contextualize(request_id="xyz789"):
    logger.info("During")  # Includes request_id

logger.info("After")  # No context

2025-01-15 14:30:45 | INFO     | __main__:main:5 - Before
2025-01-15 14:30:46 | INFO     | __main__:main:8 - During request_id=xyz789
2025-01-15 14:30:47 | INFO     | __main__:main:10 - After

with logger.contextualize(user="alice"):
    logger.info("Outer")  # user=alice

    with logger.contextualize(action="login"):
        logger.info("Inner")  # user=alice action=login

    logger.info("Back to outer")  # user=alice

2025-01-15 14:30:45 | INFO     | __main__:main:2 - Outer user=alice
2025-01-15 14:30:46 | INFO     | __main__:main:5 - Inner user=alice action=login
2025-01-15 14:30:47 | INFO     | __main__:main:7 - Back to outer user=alice

def process_payment(user_id, amount):
    with logger.contextualize(user_id=user_id, amount=amount):
        logger.info("Starting payment")
        # validate_payment()
        logger.success("Payment complete")

process_payment("alice", 100.50)

2025-01-15 14:30:45 | INFO     | __main__:process_payment:4 - Starting payment user_id=alice amount=100.5
2025-01-15 14:30:46 | SUCCESS  | __main__:process_payment:6 - Payment complete user_id=alice amount=100.5

Bind vs Contextualize¶

Exception Handling Methods¶

logger.exception()¶

Log exception with full traceback.

Signature¶

logger.exception(message: str = "", **kwargs) -> None

Parameters Table¶

Returns¶

• Type: None
• Description: Logs at ERROR level with full traceback.

Examples¶

from logly import logger

logger.add("console")

try:
    result = 1 / 0
except ZeroDivisionError:
    logger.exception("Math error occurred")

2025-01-15 14:30:45 | ERROR    | __main__:main:8 - Math error occurred
Traceback (most recent call last):
  File "app.py", line 6, in <module>
    result = 1 / 0
             ~~^~~
ZeroDivisionError: division by zero

try:
    amount = -100
    if amount < 0:
        raise ValueError("Amount must be positive")
except ValueError as e:
    logger.exception("Payment validation failed", amount=amount, user="alice")

2025-01-15 14:30:45 | ERROR    | __main__:main:6 - Payment validation failed amount=-100 user=alice
Traceback (most recent call last):
  File "app.py", line 4, in <module>
    raise ValueError("Amount must be positive")
ValueError: Amount must be positive

def handle_request(request_id, data):
    try:
        if not data:
            raise ValueError("Empty data")
        # validate_data(data)
        # process_data(data)
    except Exception as e:
        logger.exception(
            "Request processing failed",
            request_id=request_id,
            error_type=type(e).__name__
        )
        raise

handle_request("req-123", None)

2025-01-15 14:30:45 | ERROR    | __main__:handle_request:9 - Request processing failed request_id=req-123 error_type=ValueError
Traceback (most recent call last):
  File "app.py", line 5, in handle_request
    raise ValueError("Empty data")
ValueError: Empty data

Use Cases¶

• 🐛 Debugging: Full traceback for error investigation
• 📊 Monitoring: Track exception types and frequency
• 🔍 Troubleshooting: Context-rich error logs
• 🚨 Alerting: Trigger alerts on critical exceptions

logger.catch()¶

Decorator and context manager to catch exceptions.

Signature¶

logger.catch(
    exception: type[Exception] | tuple[type[Exception], ...] = Exception,
    level: str = "ERROR",
    reraise: bool = False,
    message: str = ""
)

Parameters Table¶

Returns¶

• Type: Decorator or context manager
• Description: Catches and logs exceptions automatically.

Examples¶

from logly import logger

logger.add("console")

with logger.catch():
    result = 1 / 0  # ZeroDivisionError
    print("This won't execute")

print("Execution continues")

2025-01-15 14:30:45 | ERROR    | __main__:main:6 - Caught exception
Traceback (most recent call last):
  File "app.py", line 6, in <module>
    result = 1 / 0
ZeroDivisionError: division by zero
Execution continues

@logger.catch(reraise=True)
def process_data(data):
    if not data:
        raise ValueError("No data provided")
    # transform(data)
    # save(data)
    return data

try:
    process_data(None)
except ValueError:
    print("Caught re-raised exception")

2025-01-15 14:30:45 | ERROR    | __main__:process_data:3 - Exception in function
Traceback (most recent call last):
  File "app.py", line 3, in process_data
    raise ValueError("No data provided")
ValueError: No data provided
Caught re-raised exception

@logger.catch(exception=(ValueError, TypeError), level="WARNING")
def parse_input(value):
    return int(value)

result1 = parse_input("abc")  # ValueError caught and logged at WARNING
result2 = parse_input(123)    # TypeError caught and logged at WARNING
print(f"Results: {result1}, {result2}")  # Both None (suppressed exceptions)

2025-01-15 14:30:45 | WARNING  | __main__:parse_input:3 - Exception caught
Traceback (most recent call last):
  File "app.py", line 3, in parse_input
    return int(value)
ValueError: invalid literal for int() with base 10: 'abc'
2025-01-15 14:30:46 | WARNING  | __main__:parse_input:3 - Exception caught
Traceback (most recent call last):
  File "app.py", line 3, in parse_input
    return int(value)
TypeError: int() argument must be a string, a bytes-like object or a real number, not 'NoneType'
Results: None, None

with logger.catch(message="Database operation failed"):
    # db.connect()
    raise ConnectionError("Could not connect")

2025-01-15 14:30:45 | ERROR    | __main__:main:3 - Database operation failed
Traceback (most recent call last):
  File "app.py", line 3, in <module>
    raise ConnectionError("Could not connect")
ConnectionError: Could not connect

Decorator vs Context Manager¶

Callback Methods¶

logger.add_callback()¶

Register callback function for log messages.

Signature¶

logger.add_callback(callback: callable) -> int

Parameters Table¶

Returns¶

• Type: int
• Description: Callback ID for later removal.

Callback Record Fields¶

Examples¶

from logly import logger

logger.add("console")

def alert_on_error(record):
    if record.get("level") == "ERROR":
        print(f"🚨 ALERT: {record['message']}")
        # send_email(admin_email, record)

callback_id = logger.add_callback(alert_on_error)

logger.info("Normal log")  # No alert
logger.error("Database failed", retry=3)  # Triggers alert

2025-01-15 14:30:45 | INFO     | __main__:main:13 - Normal log
🚨 ALERT: Database failed
2025-01-15 14:30:46 | ERROR    | __main__:main:14 - Database failed retry=3

error_count = 0

def count_errors(record):
    global error_count
    if record.get("level") in ["ERROR", "CRITICAL"]:
        error_count += 1

logger.add_callback(count_errors)

logger.info("Info log")
logger.error("Error 1")
logger.error("Error 2")
logger.critical("Critical error")
print(f"Total errors: {error_count}")  # 3

Total errors: 3

def custom_format(record):
    level = record.get("level")
    message = record.get("message")
    timestamp = record.get("timestamp", "unknown")

    print(f"[{timestamp}] {level}: {message}")

logger.add_callback(custom_format)
logger.info("Custom formatted log")

[2025-01-15T14:30:45.123Z] INFO: Custom formatted log

payments_db = []

def process_payment_logs(record):
    if record.get("event_type") == "payment":
        amount = record.get("amount")
        user = record.get("user")
        payments_db.append({"user": user, "amount": amount})

logger.add_callback(process_payment_logs)

logger.info("Payment received", event_type="payment", amount=100, user="alice")
logger.info("User login", event_type="auth", user="bob")  # Not processed

print(f"Payments: {payments_db}")

Payments: [{'user': 'alice', 'amount': 100}]

Use Cases¶

• 🚨 Alerting: Send notifications for errors
• 📊 Metrics: Collect statistics from logs
• 💾 Storage: Send logs to external systems
• 🎨 Formatting: Custom output formatting
• 🔍 Filtering: Process specific log types

logger.remove_callback()¶

Remove callback by ID.

Signature¶

logger.remove_callback(callback_id: int) -> bool

Parameters Table¶

Returns¶

• Type: bool
• Description: True if removed, False if ID not found.

Example¶

from logly import logger

logger.add("console")

def my_callback(record):
    print(f"📝 Callback: {record['message']}")

callback_id = logger.add_callback(my_callback)
logger.info("With callback")

logger.remove_callback(callback_id)
logger.info("Without callback")

Explanation: Removes a callback by its ID. After removal, the callback is no longer invoked for new logs. Returns True if removed successfully.

Expected Output:

📝 Callback: With callback
2025-01-15 14:30:45 | INFO     | __main__:main:9 - With callback
2025-01-15 14:30:46 | INFO     | __main__:main:12 - Without callback

Utility Methods¶

logger.enable()¶

Enable logging (resume after disable()).

Signature¶

logger.enable() -> None

Example¶

from logly import logger

logger.add("console")

logger.disable()
logger.info("Not logged")

logger.enable()
logger.info("Logged")

Explanation: Re-enables logging after it was disabled. All log calls after enable() will be processed normally.

Expected Output:

2025-01-15 14:30:45 | INFO     | __main__:main:8 - Logged

logger.disable()¶

Disable logging temporarily.

Signature¶

logger.disable() -> None

Example¶

from logly import logger

logger.add("console")

logger.info("Logged")

logger.disable()
logger.info("Not logged")
logger.error("Not logged either")

logger.enable()
logger.info("Logged again")

Explanation: Temporarily disables all logging. No logs are written to any sink while disabled. Useful for suppressing logs during specific operations or tests.

Expected Output:

2025-01-15 14:30:45 | INFO     | __main__:main:5 - Logged
2025-01-15 14:30:48 | INFO     | __main__:main:12 - Logged again

Use Cases¶

• 🧪 Testing: Silence logs during tests
• 🎛️ Feature Flags: Conditional logging
• 🔇 Quiet Mode: Suppress logs temporarily

logger.complete()¶

Flush all pending async writes to disk.

Signature¶

logger.complete() -> None

Returns¶

• Type: None
• Description: Blocks until all buffered logs are written to files.

Examples¶

from logly import logger
import sys

logger.add("app.log", async_write=True)
logger.info("Final message")
logger.complete()  # Ensure all written
# sys.exit(0)

id = logger.add("app.log", async_write=True)
logger.info("Important message")

logger.complete()  # Flush before reading
content = logger.read(id)
print(f"Content: {content[:50]}...")  # First 50 chars

Content: 2025-01-15 14:30:45 | INFO     | __main__:main...