logspark 0.12.0

Logging control plane and unifier

Drop-in logging foundation for Python projects.

Documentation QuickStart

---

LogSpark is a configuration and integration layer over Python's standard logging module. It adds lifecycle enforcement, environment-aware output policy, and corrected defaults — without replacing stdlib logging or introducing a new API. Every handler, filter, and formatter is a plain stdlib object.

---

Installation

pip install logspark

Optional extras:

pip install logspark[color]   # Rich terminal output with layout and color
pip install logspark[json]    # Structured single-line JSON output
pip install logspark[trace]   # Datadog DDTrace correlation injection
pip install logspark[all]     # All of the above

---

Quick Start

Minimal setup

from logspark.Instance import spark_logger as logger

logger.configure()
logger.info("Application started")

configure() with no arguments gives you terminal output to stdout, INFO level and above, color if your terminal supports it, compact tracebacks, and relative file paths in log lines.

Set the log level

import logging
from logspark.Instance import spark_logger as logger

logger.configure(level=logging.DEBUG)

Standard stdlib level constants and string names both work.

Log exceptions

try:
    result = 1 / 0
except ZeroDivisionError:
    logger.exception("Calculation failed")

Attach structured fields

logger.info("Request completed", extra={
    "method": "GET",
    "path": "/api/users",
    "status": 200,
    "duration_ms": 42,
})

JSON output

import logging
from logspark.Instance import spark_logger as logger
from logspark.Handlers import SparkJsonHandler

logger.configure(level=logging.INFO, handler=SparkJsonHandler())
logger.info("Structured record", extra={"env": "production"})

Rich terminal output

import logging
from logspark.Instance import spark_logger as logger
from logspark.Handlers.Rich.SparkRichHandler import SparkRichHandler

logger.configure(level=logging.DEBUG, handler=SparkRichHandler())
logger.debug("Rich layout with columns, color, and path resolution")

Silence or unify third-party loggers

import logging
import httpx
from logspark.Instance import spark_logger as logger, spark_log_manager

logger.configure()

spark_log_manager.adopt_all()
spark_log_manager.unify(
    spark_logger_instance=logger,
    level=logging.WARNING,
    propagate=False,
)

Scoped debug level

import logging
from logspark import TempLogLevel
from logspark.Instance import spark_logger as logger
from logspark.Handlers import SparkTerminalHandler

logger.configure(level=logging.INFO, handler=SparkTerminalHandler())

with TempLogLevel(logging.DEBUG):
    logger.debug("Visible only inside this block")

---

Key features

Feature	Description
Lifecycle enforcement	configure -> freeze -> use: configuration happens once, explicitly
Output modes	Terminal with color or JSON, switchable via environment variable
Traceback control	Hide, compact, or full tracebacks per-logger
Scoped debugging	Temporarily lower the log level for a block without changing config
Third-party management	Suppress or unify noisy loggers without touching their source
stdlib compatibility	Every component works standalone with any logging.Logger

---

Where to call configure()

At process startup, before any other module uses the logger:

# main.py
import logging
from logspark.Instance import spark_logger as logger

logger.configure(level=logging.INFO)

from myapp import run
run()

If a log record is emitted before configure(), LogSpark uses a minimal fallback format and emits a one-time warning. It does not silently discard records.

---

Documentation

• Concepts
• Lifecycle
• Output Modes
• Environment Variables
• Scoped Logging
• Third Party Loggers
• Component Reference

---

License

MIT — see LICENSE for details.