# 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.
## 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 = [
'django_tracing.middleware.TraceMiddleware',
# ... other middleware
]
# Required: Service name for tracing
TRACING_SERVICE_NAME = "my-django-service"
```
### 2. Using the Traced HTTP Client
```python
from jaegertrace.httpclient import HttpClient
# Create a traced HTTP client
client = HttpClient(url='http://httpbin.org/get')
# Make requests - automatically traced
response = client.get("/users/123")
response = client.post("/users", json={"name": "John"})
```
## 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
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
},
}
```
## 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
LOGGING = {
'loggers': {
'jaegertrace': {
'handlers': ['console'],
'level': 'DEBUG',
'propagate': False,
},
},
}
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Changelog
### Version 0.0.1
- Initial release
- HTTP request tracing
Raw data
{
"_id": null,
"home_page": "https://github.com/lcoolcool/django-jaeger-middleware-plus",
"name": "django-jaeger-middleware-plus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "django, jaegeropentracingmicroservice",
"author": "zhaishuaishuai",
"author_email": "zhaishuaishuai001@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1a/9b/4002619f3119ec9539bb494b9f9ed400428e24e60a042865c56e6617b38e/django_jaeger_middleware_plus-0.0.2.tar.gz",
"platform": null,
"description": "# Django Distributed Tracing\n\nA comprehensive Django middleware package for distributed tracing with Jaeger, supporting HTTP requests, Database queries, Redis operations, Celery tasks, and RocketMQ messaging.\n\nI read Jaeger - Distributed Tracing System on [github](https://github.com/jaegertracing/jaeger-client-python) and make it plus.\n\n## Features\n\n- **HTTP Request Tracing**: Automatic tracing of incoming HTTP requests and outgoing HTTP calls\n- **Database Query Tracing**: Track Django ORM queries with performance metrics\n- **Redis Operation Tracing**: Monitor Redis commands and operations\n- **Celery Task Tracing**: Distributed tracing across Celery task queues\n- **RocketMQ Message Tracing**: Trace message production and consumption\n- **Configurable Components**: Enable/disable specific tracing components\n- **Performance Monitoring**: Track slow queries, long-running requests, and bottlenecks\n- **Error Tracking**: Automatic error logging and span tagging\n\n## Installation\n\n```bash\npip install django-jaeger-middleware-plus\n```\n\n## Quick Start\n\n### 1. Add to Django Settings\n\n```python\n# settings.py\n\nINSTALLED_APPS = [\n # ... other apps\n 'jaegertrace',\n]\n\nMIDDLEWARE = [\n 'django_tracing.middleware.TraceMiddleware',\n # ... other middleware\n]\n\n# Required: Service name for tracing\nTRACING_SERVICE_NAME = \"my-django-service\"\n```\n\n### 2. Using the Traced HTTP Client\n\n```python\nfrom jaegertrace.httpclient import HttpClient\n\n# Create a traced HTTP client\nclient = HttpClient(url='http://httpbin.org/get')\n\n# Make requests - automatically traced\nresponse = client.get(\"/users/123\")\nresponse = client.post(\"/users\", json={\"name\": \"John\"})\n```\n\n## Configuration Reference\n\n### Tracer Configuration\n\n```python\nTRACER_CONFIG = {\n \"sampler\": {\n \"type\": \"const\", # const, probabilistic, rate_limiting\n \"param\": 1, # Sample rate (0.0 to 1.0)\n },\n \"local_agent\": {\n \"reporting_host\": \"localhost\",\n \"reporting_port\": 6832,\n },\n \"trace_id_header\": \"trace-id\",\n \"baggage_header_prefix\": \"jaeger-\",\n \"logging\": True,\n \"metrics\": False,\n}\n```\n\n### Component Configuration\n\n```python\nTRACING_CONFIG = {\n \"http_requests\": {\n \"enabled\": True,\n \"trace_headers\": True, # Inject tracing headers\n \"ignore_urls\": [\"/health\", \"/metrics\", \"/favicon.ico\"], # URLs to skip\n \"max_tag_value_length\": 1024, # Max length for tag values\n },\n}\n```\n## Production Considerations\n\n### Sampling\n\nIn production, consider using probabilistic sampling to reduce overhead:\n\n```python\nTRACER_CONFIG = {\n \"sampler\": {\n \"type\": \"probabilistic\",\n \"param\": 0.1, # Sample 10% of traces\n }\n}\n```\n\n### Performance Impact\n\n- Database query tracing adds minimal overhead (~1-2ms per query)\n- HTTP request tracing adds ~5-10ms per request\n- Redis tracing adds ~1ms per operation\n- Consider disabling SQL logging in production\n\n### Resource Usage\n\n- Each span consumes ~1KB of memory\n- Jaeger agent buffers traces locally before sending\n- Monitor memory usage with high-throughput applications\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Traces not appearing in Jaeger**\n - Check Jaeger agent connectivity\n - Verify sampling configuration\n - Check service name configuration\n\n2. **High memory usage**\n - Reduce sampling rate\n - Disable detailed logging (SQL, message bodies)\n - Check for span leaks (unfinished spans)\n\n3. **Performance degradation**\n - Tune slow query thresholds\n - Disable non-essential component tracing\n - Use asynchronous reporting\n\n### Debug Mode\n\nEnable debug logging to troubleshoot issues:\n\n```python\nLOGGING = {\n 'loggers': {\n 'jaegertrace': {\n 'handlers': ['console'],\n 'level': 'DEBUG',\n 'propagate': False,\n },\n },\n}\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Changelog\n\n### Version 0.0.1\n- Initial release\n- HTTP request tracing\n",
"bugtrack_url": null,
"license": null,
"summary": "A Django middleware for distributed tracing with Jaeger",
"version": "0.0.2",
"project_urls": {
"Bug Reports": "https://github.com/lcoolcool/django-jaeger-middleware-plus/issues",
"Documentation": "https://github.com/lcoolcool/django-jaeger-middleware-plus",
"Homepage": "https://github.com/lcoolcool/django-jaeger-middleware-plus",
"Source": "https://github.com/lcoolcool/django-jaeger-middleware-plus"
},
"split_keywords": [
"django",
" jaegeropentracingmicroservice"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6e149d4a5effd9118a081fefeae43dd5e59475b72dc25a62ad4304bca9117a85",
"md5": "6b6b93988b5a07529b64d302baa52d60",
"sha256": "e0ac31fffef9a08b34e5e665bb19753d8618c7da15a6e71e255e9326525207c6"
},
"downloads": -1,
"filename": "django_jaeger_middleware_plus-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6b6b93988b5a07529b64d302baa52d60",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14849,
"upload_time": "2025-09-09T03:25:41",
"upload_time_iso_8601": "2025-09-09T03:25:41.427687Z",
"url": "https://files.pythonhosted.org/packages/6e/14/9d4a5effd9118a081fefeae43dd5e59475b72dc25a62ad4304bca9117a85/django_jaeger_middleware_plus-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1a9b4002619f3119ec9539bb494b9f9ed400428e24e60a042865c56e6617b38e",
"md5": "20f877639c06a0c72a39d29d38cf8f12",
"sha256": "5045349f3b67174bd0caa6a3f4b9e8c5e0eb82c1d0af27fb985255eacc002eea"
},
"downloads": -1,
"filename": "django_jaeger_middleware_plus-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "20f877639c06a0c72a39d29d38cf8f12",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 12524,
"upload_time": "2025-09-09T03:25:42",
"upload_time_iso_8601": "2025-09-09T03:25:42.982935Z",
"url": "https://files.pythonhosted.org/packages/1a/9b/4002619f3119ec9539bb494b9f9ed400428e24e60a042865c56e6617b38e/django_jaeger_middleware_plus-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 03:25:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lcoolcool",
"github_project": "django-jaeger-middleware-plus",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Django",
"specs": [
[
">=",
"2.2"
],
[
"<",
"5.0"
]
]
},
{
"name": "jaeger-client",
"specs": [
[
">=",
"4.6.1"
],
[
"<",
"5.0"
]
]
},
{
"name": "opentracing",
"specs": [
[
">=",
"2.4.0"
],
[
"<",
"3.0"
]
]
},
{
"name": "requests",
"specs": [
[
"<",
"3.0"
],
[
">=",
"2.25.1"
]
]
},
{
"name": "redis",
"specs": [
[
"<",
"5.0"
],
[
">=",
"3.5.3"
]
]
},
{
"name": "celery",
"specs": [
[
">=",
"5.0.0"
],
[
"<",
"6.0"
]
]
},
{
"name": "rocketmq-client-python",
"specs": [
[
">=",
"2.0.0"
],
[
"<",
"3.0"
]
]
}
],
"lcname": "django-jaeger-middleware-plus"
}
JSON
