Logging

There are two ways to send logs to Auralog from Python, and you can freely mix them.

1. Direct API

Call auralog methods directly:

from auralog import auralog

auralog.debug("hit cache", metadata={"key": "user:42"})
auralog.info("user signed in", metadata={"user_id": "123"})
auralog.warn("slow query", metadata={"duration_ms": 1240})
auralog.error("payment failed", metadata={"order_id": "abc"})
auralog.fatal("db connection lost")

# Attach a traceback to any error/fatal:
try:
    risky()
except Exception as e:
    auralog.error("task crashed", metadata={"task": "ingest"}, exc_info=e)

2. Stdlib logging bridge (recommended for existing codebases)

Python’s logging module is used everywhere — including frameworks (Django, Flask, FastAPI) and libraries (requests, SQLAlchemy, Celery). AuralogHandler captures those logs without requiring code changes.

import logging
from auralog import init, AuralogHandler

init(api_key="aura_your_api_key", environment="production")

# Attach once on the root logger
logging.getLogger().addHandler(AuralogHandler())
logging.getLogger().setLevel(logging.INFO)

# Normal logging.* calls flow to Auralog
logging.info("payment processed", extra={"order_id": "abc"})
logger = logging.getLogger("myapp.billing")
logger.warning("slow request", extra={"duration_ms": 1240})

Level mapping

stdlib level	Auralog level
DEBUG	debug
INFO	info
WARNING	warn
ERROR	error
CRITICAL	fatal

Metadata

Anything you pass in extra={...} is forwarded as metadata. Reserved LogRecord fields (like message, name, asctime) are filtered out automatically so they don’t pollute your data.

Tracebacks

logging.exception() and logger.error(..., exc_info=True) automatically attach the current traceback to the Auralog log entry.

When to use which

• Greenfield project: direct API. Explicit call sites, no stdlib config to learn.
• Existing codebase, lots of logging usage: handler. Zero rewrites, catches library logs too.
• Both: fine. Use auralog.info(...) at critical paths, let the handler catch the long tail.