datadog-async-handler

Datadog Async Handler

A modern, high-performance Python logging handler that sends logs directly to Datadog via HTTP API with asynchronous batching, retry logic, and comprehensive error handling.

✨ Features

• 🚀 High Performance: Asynchronous batching and background processing
• 🔄 Reliable Delivery: Automatic retry with exponential backoff
• 📊 Batching: Configurable batch size and flush intervals
• 🏷️ Rich Metadata: Automatic service, environment, and custom tag support
• 🔧 Easy Integration: Drop-in replacement for standard logging handlers
• 🌐 Multi-Site Support: Works with all Datadog sites (US, EU, etc.)
• 📝 Type Safe: Full type hints and mypy compatibility
• ⚡ Modern: Built with Python 3.9+ and latest best practices

🚀 Quick Start

Installation

pip install datadog-async-handler

Basic Usage

import logging
from datadog_http_handler import DatadogHTTPHandler

# Configure the handler
handler = DatadogHTTPHandler(
    api_key="your-datadog-api-key",  # or set DD_API_KEY env var
    service="my-application",
    source="python",
    tags="env:production,team:backend"
)

# Set up logging
logger = logging.getLogger(__name__)
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# Start logging!
logger.info("Application started successfully", extra={
    "user_id": "12345",
    "action": "startup"
})

Environment Variables

The handler automatically picks up standard Datadog environment variables:

export DD_API_KEY="your-api-key"
export DD_SERVICE="my-application"
export DD_ENV="production"
export DD_VERSION="1.2.3"
export DD_TAGS="team:backend,component:api"
export DD_SITE="datadoghq.com"  # or datadoghq.eu, ddog-gov.com, etc.

📖 Documentation

Configuration Options

Parameter	Type	Default	Description
api_key	str	None	Datadog API key (required)
site	str	"datadoghq.com"	Datadog site
service	str	None	Service name
source	str	"python"	Log source
hostname	str	None	Hostname
tags	str	None	Comma-separated tags
batch_size	int	10	Number of logs per batch
flush_interval_seconds	float	5.0	Batch flush interval
timeout_seconds	float	10.0	Request timeout
max_retries	int	3	Maximum retry attempts

Framework Integration Examples

Django

# settings.py
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'datadog': {
            'class': 'datadog_http_handler.DatadogHTTPHandler',
            'api_key': 'your-api-key',
            'service': 'django-app',
            'source': 'django',
        },
    },
    'root': {
        'handlers': ['datadog'],
        'level': 'INFO',
    },
}

FastAPI

import logging
from fastapi import FastAPI
from datadog_http_handler import DatadogHTTPHandler

app = FastAPI()

# Configure logging
handler = DatadogHTTPHandler(service="fastapi-app", source="fastapi")
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.INFO)

@app.get("/")
async def root():
    logging.info("API endpoint called", extra={"endpoint": "/"})
    return {"message": "Hello World"}

Flask

import logging
from flask import Flask
from datadog_http_handler import DatadogHTTPHandler

app = Flask(__name__)

# Configure logging
handler = DatadogHTTPHandler(service="flask-app", source="flask")
app.logger.addHandler(handler)
app.logger.setLevel(logging.INFO)

@app.route("/")
def hello():
    app.logger.info("Flask endpoint called", extra={"endpoint": "/"})
    return "Hello World!"

🔧 Development

Setup

# Clone the repository
git clone https://github.com/enlyft/datadog-http-handler.git
cd datadog-http-handler

# Install UV (modern Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
hatch run test

# Run with coverage
hatch run test-cov

# Run specific tests
hatch run test tests/test_handler.py::test_basic_logging

Code Quality

# Format code
hatch run format

# Lint code
hatch run lint

# Type checking
hatch run type-check

# Run all checks
hatch run all

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

📋 Requirements

• Python 3.9+
• datadog-api-client>=2.0.0

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Documentation
• PyPI Package
• GitHub Repository
• Issue Tracker
• Datadog Logs API Documentation

🆚 Comparison with Other Solutions

Feature	datadog-async-handler	datadog-http-handler	python-datadog	datadog-logger
Async Batching	✅	❌	❌	❌
Retry Logic	✅	❌	❌	❌
Type Hints	✅	❌	❌	❌
Modern Python	✅ (3.9+)	❌ (3.6+)	❌ (2.7+)	❌ (3.6+)
Official API Client	✅	❌	❌	❌
Background Processing	✅	❌	❌	❌
Memory Efficient	✅	❌	❌	❌
Active Maintenance	✅	❌ (2019)	✅	❌
Comprehensive Tests	✅	❌	✅	❌

---

Made with ❤️ for the Python and Datadog communities.

This site is open source. Improve this page.