Usage

Fast path to start logging, with copy-paste sink configs for all supported sink types.

1) Install with pip in a virtual environment

install.sh

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install jazzmine-logging

2) Installation options

# Core package only
pip install jazzmine-logging

# One optional sink extra
pip install "jazzmine-logging[sentry]"

# Multiple extras together
pip install "jazzmine-logging[sentry,redis,kafka]"

# All extras
pip install "jazzmine-logging[all]"

# Local editable install
pip install -e ".[all]"

Extra → sink mapping

Extra	Needed for sink type
`sentry`	sentry
`kafka`	kafka
`redis`	redis
`honeycomb`	honeycomb
`aws`	cloudwatch
`gcp`	pubsub

No extra is required for: console, file, http, datadog, loki, newrelic, logstash, vector, fluentbit, promtail, graylog.

3) Minimal example (sync, console)

logging_sync.py

from jazzmine.logging import BaseLogger

config = {
    "name": "demo-app",
    "level": "INFO",
    "json": True,
    "sinks": [{"type": "console"}],
}

logger = BaseLogger(config)
logger.resolve_config()

logger.info("service started", version="0.1.0")
logger.warning("slow response", endpoint="/health", latency_ms=230)
logger.error("request failed", status=500, request_id="req-123")

4) Minimal example (async + sink lifecycle)

For sink adapters from the registry (sentry, redis, kafka, etc.), call start_async_workers() before logging and shutdown() on exit.

logging_async.py

import asyncio
from jazzmine.logging import BaseLogger

config = {
    "name": "demo-app",
    "level": "INFO",
    "json": True,
    "sinks": [
        {"type": "console"},
        {"type": "loki", "url": "http://localhost:3100/loki/api/v1/push"},
    ],
}


async def main():
    logger = BaseLogger(config)
    logger.resolve_config()
    await logger.start_async_workers()

    logger.info("sync log")
    await logger.ainfo("async log", request_id="abc-123")

    await logger.shutdown()


asyncio.run(main())

5) Sink examples (all supported sink types)

Copy one or more sink entries into your sinks list.

sink_examples.py

SINK_EXAMPLES = {
    "console": {"type": "console"},
    "file": {"type": "file", "path": "logs/app.log", "rotate": {"when": "midnight", "backupCount": 7}},
    "http_sync": {"type": "http", "url": "https://collector.example.com/logs", "method": "POST"},
    "datadog": {"type": "datadog", "api_key": "<DATADOG_API_KEY>", "site": "datadoghq.com", "service": "demo-app"},
    "loki": {"type": "loki", "url": "http://localhost:3100/loki/api/v1/push", "labels": {"job": "demo-app"}},
    "newrelic": {"type": "newrelic", "license_key": "<NEW_RELIC_LICENSE_KEY>", "region": "us"},
    "sentry": {"type": "sentry", "dsn": "<SENTRY_DSN>", "environment": "production", "traces_sample_rate": 0.1},
    "honeycomb": {"type": "honeycomb", "api_key": "<HONEYCOMB_API_KEY>", "dataset": "demo-app"},
    "kafka": {"type": "kafka", "bootstrap_servers": ["localhost:9092"], "topic": "app-logs", "async": True},
    "redis": {"type": "redis", "host": "localhost", "port": 6379, "db": 0, "stream_key": "logs:demo-app"},
    "cloudwatch": {"type": "cloudwatch", "region": "us-east-1", "log_group": "/logs/demo-app", "log_stream": "default"},
    "pubsub": {"type": "pubsub", "project_id": "my-gcp-project", "topic": "app-logs"},
    "vector": {"type": "vector", "url": "http://localhost:8686"},
    "graylog": {"type": "graylog", "host": "localhost", "port": 12201, "protocol": "http"},
}

6) Practical notes

Keep API keys and DSNs in environment variables, then inject them into your config.
For console/file/http only, resolve_config() is enough for basic sync logs.
For registry sink adapters (datadog, kafka, redis, …), call await logger.start_async_workers() before logging.
Always call await logger.shutdown() for clean resource cleanup.

Deep reference

Base logger runtime — configuration resolution, worker lifecycle, sync/async fan-out.
Config system — loader, validator, registry-based sink wiring, and defaults.

On this page