Metadata-Version: 2.4
Name: django-jaeger-middleware-plus
Version: 0.1.6
Summary: A Django middleware for distributed tracing with Jaeger
Home-page: https://github.com/lcoolcool/django-jaeger-middleware-plus
Author: zhaishuaishuai
Author-email: zhaishuaishuai001@gmail.com
Project-URL: Bug Reports, https://github.com/lcoolcool/django-jaeger-middleware-plus/issues
Project-URL: Source, https://github.com/lcoolcool/django-jaeger-middleware-plus
Project-URL: Documentation, https://github.com/lcoolcool/django-jaeger-middleware-plus
Keywords: django,django-jaeger-middleware,jaegeropentracingmicroservice
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=2.2
Requires-Dist: jaeger-client>=4.6.1
Requires-Dist: opentracing>=2.4.0
Requires-Dist: requests>=2.25.1
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-django>=2.2; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.812; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Django Distributed Tracing

A comprehensive Django middleware package for distributed tracing with Jaeger, supporting HTTP requests, Database queries, Redis operations, Celery tasks, and RocketMQ messaging.

I read Jaeger - Distributed Tracing System on [github](https://github.com/jaegertracing/jaeger-client-python) and make it plus.

[![Pypi Version](https://badge.fury.io/py/django-nacos-microservice.svg)](https://badge.fury.io/py/django-jaeger-middleware-plus)

## Features

- **HTTP Request Tracing**: Automatic tracing of incoming HTTP requests and outgoing HTTP calls
- **Database Query Tracing**: Track Django ORM queries with performance metrics
- **Redis Operation Tracing**: Monitor Redis commands and operations
- **Celery Task Tracing**: Distributed tracing across Celery task queues
- **RocketMQ Message Tracing**: Trace message production and consumption
- **Configurable Components**: Enable/disable specific tracing components
- **Performance Monitoring**: Track slow queries, long-running requests, and bottlenecks
- **Error Tracking**: Automatic error logging and span tagging

## Installation

```bash
pip install django-jaeger-middleware-plus
```

## Quick Start

### 1. Add to Django Settings

```python
# settings.py

INSTALLED_APPS = [
    # ... other apps
    'jaegertrace',
]

MIDDLEWARE = [
    'jaegertrace.middleware.TraceMiddleware',
    # ... other middleware
]

# Required: Service name for tracing
TRACING_SERVICE_NAME = "my-django-service"
```

## Configuration Reference

### Tracer Configuration

```python
TRACER_CONFIG = {
    "sampler": {
        "type": "const",        # const, probabilistic, rate_limiting
        "param": 1,             # Sample rate (0.0 to 1.0)
    },
    "local_agent": {
        "reporting_host": "localhost",
        "reporting_port": 6832,
    },
    "trace_id_header": "trace-id",
    "baggage_header_prefix": "jaeger-",
    "logging": True,
    "metrics": False,
}
```

### Component Configuration

```python
# settings.py

TRACING_CONFIG = {
    "http_requests": {
        "enabled": True,
        "trace_headers": True,  # Inject tracing headers
        "ignore_urls": ["/health", "/metrics", "/favicon.ico"],  # URLs to skip
        "max_tag_value_length": 1024,  # Max length for tag values, default 1024
    },
    "database": {
        "enabled": True,
        "slow_query_threshold": 100,  # Milliseconds
        "log_sql": True,  # Include SQL in spans
        "ignore_sqls": ["SHOW TABLES", "DESCRIBE"],  # SQL commands to skip, default ["SHOW TABLES", "DESCRIBE"]
        "max_query_length": 1000,  # Truncate long queries, default 1000
    },
    "redis": {
        "enabled": True,
        "log_command": True,  # Include command in spans
        "ignore_commands": ["PING", "INFO"],  # Redis commands to skip
        "max_command_length": 500,  # Truncate long commands, default 500
    },
    "celery": {
        "enabled": True,
        "ignore_tasks": [],  # Celery tasks to skip
    },
    "rocketmq": {
        "enabled": True,
        "trace_message_body": False,  # Include message content
        "ignore_topics": [],  # RocketMQ topics to skip
    },
}
```

## Usage

### 1. Using the Traced HTTP Client

```python
from jaegertrace.httpclient import HttpClient

# Create a traced HTTP client
client = HttpClient()

# Make requests - automatically traced
response = client.get("/users/123")
response = client.post("/users", json={"name": "John"})

```

## Production Considerations

### Sampling

In production, consider using probabilistic sampling to reduce overhead:

```python
TRACER_CONFIG = {
    "sampler": {
        "type": "probabilistic",
        "param": 0.1,  # Sample 10% of traces
    }
}
```

### Performance Impact

- Database query tracing adds minimal overhead (~1-2ms per query)
- HTTP request tracing adds ~5-10ms per request
- Redis tracing adds ~1ms per operation
- Consider disabling SQL logging in production

### Resource Usage

- Each span consumes ~1KB of memory
- Jaeger agent buffers traces locally before sending
- Monitor memory usage with high-throughput applications

## Troubleshooting

### Common Issues

1. **Traces not appearing in Jaeger**
   - Check Jaeger agent connectivity
   - Verify sampling configuration
   - Check service name configuration

2. **High memory usage**
   - Reduce sampling rate
   - Disable detailed logging (SQL, message bodies)
   - Check for span leaks (unfinished spans)

3. **Performance degradation**
   - Tune slow query thresholds
   - Disable non-essential component tracing
   - Use asynchronous reporting

## Debug Mode
Enable debug logging to troubleshoot issues:
```python
# settings.py

LOGGING = {
    'loggers': {
        'django_tracing': {
            'handlers': ['console'],
            'level': 'DEBUG',
            'propagate': False,
        },
    },
}
```

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

## Contact
Email me with any questions: <zhaishuaishuai001@gmail.com>.
