Logistro

Warnings

• gotcha When switching between human-readable (`set_human()`) and structured (`set_structured()`) logging formats, these functions must be called *before* any other logging calls. Calling them mid-execution with an existing logger requires an additional step (`logistro.coerce_logger(logistro.getLogger())`) to ensure the formatter is updated.
  Fix: Call `logistro.set_structured()` or `logistro.set_human()` early in your application's lifecycle, ideally before `logistro.getLogger()` is first called for the root logger. If changing mid-execution, re-coerce the logger: `logistro.set_structured(); logistro.coerce_logger(logistro.getLogger())`.
• gotcha The `logistro.betterConfig()` function, which is implicitly called by `logistro.getLogger()`, accepts most arguments identical to Python's standard `logging.basicConfig()` but *ignores* the `format` argument. This is because Logistro manages its own formatting based on `set_human()` or `set_structured()`.
  Fix: Do not pass a `format` argument to `logistro.betterConfig()`. Instead, use `logistro.set_human()` (default) or `logistro.set_structured()` to control the output format globally.
• gotcha When using `logistro.getPipeLogger()` to capture subprocess output, it returns a pipe file descriptor. It is crucial to manually close this pipe using `os.close(pipe)` after the subprocess has completed to prevent resource leaks.
  Fix: Always ensure `os.close(pipe)` is called after the subprocess that uses the pipe has terminated and its output has been consumed or is no longer needed.

Install

• pip install logistro Install stable release

Imports

• getLogger

  import logistro
  logger = logistro.getLogger(__name__)

  This is the primary way to obtain a logger, and it ensures Logistro's default configuration is applied.
• getPipeLogger

  import logistro
  pipe, logger = logistro.getPipeLogger(__name__ + '-subprocess')

  Used for routing subprocess stderr to the Logistro logger.
• set_structured

  import logistro
  logistro.set_structured()

  Configures all loggers to output in JSON format. Must be called before any logging output.
• set_human

  import logistro
  logistro.set_human()

  Configures all loggers to output in human-readable format (default). Must be called before any logging output.

Quickstart

This quickstart demonstrates how to initialize Logistro, use its custom logging levels (`debug2`), integrate with subprocesses using `getPipeLogger()`, and dynamically switch between human-readable and structured (JSON) output formats.

import logistro
import os
import subprocess

# Basic logger setup (automatically configured by getLogger)
logger = logistro.getLogger(__name__)

logger.debug2("This is a custom debug level (more verbose)")
logger.debug("This is a standard debug message")
logger.info("Application started")

try:
    # Example with getPipeLogger for subprocesses
    # Note: In a real app, manage 'cli_command' securely (e.g., using shlex.split)
    cli_command = [os.environ.get('EXAMPLE_SUBPROCESS_COMMAND', 'ls'), '-l']
    pipe, sub_logger = logistro.getPipeLogger(__name__ + '-subprocess')
    process = subprocess.Popen(cli_command, stderr=pipe)
    process.wait() # Wait for the subprocess to finish
    os.close(pipe) # Crucial to close the pipe after use
    sub_logger.info("Subprocess finished with exit code: %s", process.returncode)

    raise ValueError("Something went wrong")
except ValueError as e:
    logger.exception("An error occurred: %s", e)

# Switch to structured logging mid-execution (affects subsequent logs)
logistro.set_structured()
logger.info("This message is now structured (JSON)", user_id="123", event="test_event")