logly 0.2.5

A Rust-powered, high-performance logging library for Python.

Documentation | API Reference | Quick Start | Contributing

A Rust-powered, high-performance logging library for Python with structured sinks, custom levels, rotation, compression, and telemetry integrations.

If you love logly, make sure to give it a star!

Prerequisites

Installation

Quick Install

pip install logly
# or
uv add logly

# Core
pip install logly                            # core only (no optional deps)

# Frameworks & Libraries
pip install "logly[rich]"                    # Rich console output
pip install "logly[fastapi]"                 # FastAPI middleware
pip install "logly[starlette]"               # Starlette middleware
pip install "logly[django]"                  # Django handler + middleware
pip install "logly[flask]"                   # Flask handler
pip install "logly[gunicorn]"                # Gunicorn worker hooks
pip install "logly[uvicorn]"                 # Uvicorn log config
pip install "logly[sqlalchemy]"              # SQLAlchemy query logging
pip install "logly[structlog]"               # Structlog processor
pip install "logly[celery]"                  # Celery task logging
pip install "logly[click]"                   # Click CLI output
pip install "logly[typer]"                   # Typer CLI output
pip install "logly[apscheduler]"             # APScheduler job logging
pip install "logly[rq]"                      # RQ worker logging
pip install "logly[tqdm]"                    # tqdm progress bar sink

# Monitoring & Observability
pip install "logly[opentelemetry]"           # OpenTelemetry export
pip install "logly[prometheus]"              # Prometheus metrics
pip install "logly[elasticsearch]"           # Elasticsearch indexing
pip install "logly[sentry]"                  # Sentry error tracking
pip install "logly[newrelic]"                # New Relic agent
# Built-in (no extra needed): datadog, seq, telemetry, loki

# Cloud Providers
pip install "logly[aws]"                     # AWS CloudWatch Logs
pip install "logly[gcloud]"                  # Google Cloud Logging
pip install "logly[azure]"                   # Azure Monitor

# Data Stores
pip install "logly[redis]"                   # Redis lists/streams
pip install "logly[kafka]"                   # Kafka topics (requires librdkafka)
pip install "logly[mongodb]"                 # MongoDB collections
pip install "logly[postgresql]"              # PostgreSQL tables
pip install "logly[rabbitmq]"                # RabbitMQ queues

# Log Aggregation (all built-in, no extra needed)
# logstash, graylog, loki use only Python stdlib

# Notifications
pip install "logly[discord]"                 # Discord webhooks (urllib by default, aiohttp optional)
pip install "logly[slack]"                   # Slack webhooks (urllib by default, slack-sdk optional)
# Built-in (no extra needed): email, http

# Utilities
pip install "logly[compression]"             # Zstandard compression

# Everything
pip install "logly[all]"                     # all of the above

# Core
uv add logly

# Frameworks & Libraries
uv add "logly[rich]"
uv add "logly[fastapi]"
uv add "logly[starlette]"
uv add "logly[django]"
uv add "logly[flask]"
uv add "logly[gunicorn]"
uv add "logly[uvicorn]"
uv add "logly[sqlalchemy]"
uv add "logly[structlog]"
uv add "logly[celery]"
uv add "logly[click]"
uv add "logly[typer]"
uv add "logly[apscheduler]"
uv add "logly[rq]"
uv add "logly[tqdm]"

# Monitoring & Observability
uv add "logly[opentelemetry]"
uv add "logly[prometheus]"
uv add "logly[elasticsearch]"
uv add "logly[sentry]"
uv add "logly[newrelic]"
# Built-in (no extra needed): datadog, seq, telemetry, loki

# Cloud Providers
uv add "logly[aws]"
uv add "logly[gcloud]"
uv add "logly[azure]"

# Data Stores
uv add "logly[redis]"
uv add "logly[kafka]"
uv add "logly[mongodb]"
uv add "logly[postgresql]"
uv add "logly[rabbitmq]"

# Log Aggregation (all built-in, no extra needed)
# logstash, graylog, loki use only Python stdlib

# Notifications
uv add "logly[discord]"
uv add "logly[slack]"
# Built-in (no extra needed): email, http

# Utilities
uv add "logly[compression]"

# Everything
uv add "logly[all]"

From Source

git clone https://github.com/muhammad-fiaz/logly.git
cd logly
uv sync
uv run maturin develop

Quick Start

from logly import logger

logger.trace("Detailed trace")
logger.debug("Debug info")
logger.info("Application started")
logger.notice("Notice message")
logger.success("Operation completed!")
logger.warning("Warning message")
logger.error("Error occurred")
logger.fail("Operation failed")
logger.critical("Critical system error!")
logger.fatal("Fatal system failure!")

logger.complete()

Custom Levels

from logly import logger

# Register a custom level with icon and color
logger.level("HTTP", no=21, color="blue", icon=">")
logger.level("DATABASE", no=22, color="magenta", icon="*")
logger.level("SECURITY", no=35, color="red", icon="!")

# Log with custom levels
logger.log("HTTP", "GET /api/users")
logger.log("DATABASE", "Connected to PostgreSQL")
logger.log("SECURITY", "Authentication failed")

# Use icon in format strings
sink_id = logger.add(
    lambda msg: print(msg, end=""),
    format="{level_icon} {level} | {message}",
    level="TRACE",
)
logger.log("HTTP", "GET /api/users")
logger.remove(sink_id)
# Output: > HTTP | GET /api/users

Usage Examples

File Logging

from logly import logger

logger.add(
    "logs/app.log",
    level="INFO",
    rotation="daily",
    retention="30 days",
    compression="gzip",
)

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

Context Binding

from logly import logger

user_logger = logger.bind(user_id="12345", request_id="abc-789")
user_logger.info("User logged in")
# Output includes: user_id=12345 request_id=abc-789

Exception Catching

from logly import logger

with logger.catch():
    risky_operation()

# With options
with logger.catch(exclude=ValueError, onerror=lambda e: print(f"Failed: {e}")):
    dangerous_call()

Multiple Sinks

from logly import logger

logger.add("app.log", level="DEBUG", rotation="daily")
logger.add("errors.log", level="ERROR", retention="90 days")
logger.add("stdout", level="INFO", colorize=True)

logger.info("All three sinks receive this")

Independent Loggers

Use Logger() when a subsystem needs a separate set of sinks that does not write to the global logger.

from logly import Logger

api_logger = Logger()
worker_logger = Logger()

api_logger.add("api.log", level="INFO")
worker_logger.add("worker.log", level="DEBUG")

api_logger.info("request accepted")
worker_logger.debug("job claimed")

Lazy Evaluation

from logly import logger

logger.opt(lazy=True).debug("Result: {}", lambda: expensive_computation())

Async Sinks

import asyncio
from logly import logger


# Async function sink
async def cloud_sink(message: str) -> None:
    await send_to_cloud(message)


# Async class-based sink
class AsyncDBSink:
    def __init__(self, db_url: str):
        self.db_url = db_url

    async def __call__(self, message: str) -> None:
        await insert_into_db(self.db_url, message)


async def main():
    logger.add(cloud_sink, level="WARNING")
    logger.add(AsyncDBSink("postgresql://localhost/logs"), level="ERROR")
    logger.warning("Sent to cloud")
    logger.error("Sent to both cloud and database")
    logger.complete()


asyncio.run(main())

Rich Markup

from logly import logger, parse_rich_markup

# Angle-bracket syntax
logger.info("<bold>Important</bold> message")
logger.error("<red>Error:</red> something went wrong")
logger.info("<bold, cyan>Combined styles</bold, cyan>")

# Rich-style bracket syntax
logger.info("[red]Error[/red] occurred")
logger.info("[bold green on white]Success[/bold green on white]")

# Parse markup manually
text = parse_rich_markup("<bold>hello</bold>", colorize=True)

Batch HTTP Sink

from logly import BatchHttpJsonSink, logger

sink = BatchHttpJsonSink(
    url="https://logs.example.com/ingest",
    batch_size=100,
    flush_interval=5,
    headers={"Authorization": "Bearer token"},
)

logger.add(sink, level="INFO")
logger.info("This will be batched and sent efficiently")

For more examples, see the documentation.

Log Levels

Architecture

Logly is built as a modular Rust workspace with a thin PyO3 binding:

Building from Source

# Install uv (if not already installed)
pip install uv

# Build the extension in development mode
uv run maturin develop

# Run Python tests
uv run pytest

# Run Rust tests
cargo test --workspace

# Lint
uv run ruff check .
cargo clippy --workspace --all-targets -- -D warnings

Documentation

Full documentation is available at: https://muhammad-fiaz.github.io/logly

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgements

Logly is backed by an independent, from-scratch Rust implementation with a Python-native API.

License

This project is licensed under the MIT License.

Links

• Documentation: https://muhammad-fiaz.github.io/logly
• PyPI: https://pypi.org/project/logly/
• Repository: https://github.com/muhammad-fiaz/logly
• Issues: https://github.com/muhammad-fiaz/logly/issues