logforge-py 0.2.0

Official Python SDK for LogForge — self-hosted log management and monitoring

logforge-py

Official Python SDK for LogForge, self-hosted log management and monitoring.

Compatible with Python 3.8+. Logs are batched and sent in a background thread.

Installation

# With requests (recommended)
pip install logforge-py[requests]

# With httpx
pip install logforge-py[httpx]

# With both
pip install logforge-py[all]

Quick Start

from logforge import LogForge

logger = LogForge(
    api_key="YOUR_API_KEY",           # from LogForge dashboard → Project Settings
    endpoint="https://logs.myapp.com", # your LogForge backend URL
    environment="production",
    channel="default",
)

logger.info("App started")
logger.warning("Cache miss rate high", metadata={"rate": 0.42})
logger.error("DB write failed", metadata={"table": "orders"}, tags=["database"])

# Capture exceptions with full traceback
try:
    1 / 0
except ZeroDivisionError as e:
    logger.capture_exception(e, channel="math")

# Flush remaining logs and stop the background thread before exit
logger.shutdown()

Auto-register shutdown

import atexit
atexit.register(logger.shutdown)

Constructor Options

Option	Type	Default	Description
api_key	str	required	Project API key
endpoint	str	required	LogForge backend base URL
environment	str	'production'	Environment tag
channel	str	'default'	Default log channel
batch_size	int	10	Max logs per flush batch
flush_interval	float	5.0	Seconds between auto-flushes
retry_attempts	int	3	Retry attempts on failure
timeout	float	10.0	HTTP request timeout (seconds)
debug	bool	False	Log SDK errors via Python logging

API

Logging

logger.info(message, **options)
logger.warning(message, **options)   # alias: warn()
logger.error(message, **options)
logger.debug(message, **options)
logger.critical(message, **options)
logger.capture_exception(exc, **options)

Every method accepts keyword options:

logger.error(
    "Payment failed",
    channel="payments",
    environment="staging",
    metadata={"order_id": "ORD-456"},
    tags=["payments", "critical-path"],
)

User Context

logger.set_user("user_123", "[e-mail]", name="John Doe")
logger.clear_user()

Channel / Environment

logger.set_channel("auth")
logger.set_environment("staging")

Flush / Shutdown

logger.flush()     # block until current queue is sent
logger.shutdown()  # flush + stop background thread

Django Integration Example

# settings.py (or apps.py AppConfig.ready())
from logforge import LogForge
import atexit

log = LogForge(api_key="YOUR_KEY", endpoint="https://logs.myapp.com")
atexit.register(log.shutdown)

# In views.py
import traceback

def my_view(request):
    try:
        do_something()
    except Exception as exc:
        log.capture_exception(exc, metadata={"path": request.path})
        raise

FastAPI / async usage

The SDK is synchronous and thread-safe. It works fine alongside async frameworks — the background flush thread runs independently.

from contextlib import asynccontextmanager
from fastapi import FastAPI
from logforge import LogForge

logger = LogForge(api_key="KEY", endpoint="https://logs.myapp.com")

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    logger.shutdown()

app = FastAPI(lifespan=lifespan)

License

MIT — see LICENCE