https://github.com/florimondmanca/ddtrace-asgi
Unofficial Datadog tracing integration for ASGI apps and frameworks
https://github.com/florimondmanca/ddtrace-asgi
asgi datadog python tracing
Last synced: 9 months ago
JSON representation
Unofficial Datadog tracing integration for ASGI apps and frameworks
- Host: GitHub
- URL: https://github.com/florimondmanca/ddtrace-asgi
- Owner: florimondmanca
- License: bsd-3-clause
- Created: 2019-10-13T18:51:53.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-12-12T23:08:21.000Z (over 5 years ago)
- Last Synced: 2025-08-16T18:51:25.365Z (10 months ago)
- Topics: asgi, datadog, python, tracing
- Language: Python
- Homepage: https://pypi.org/project/ddtrace-asgi
- Size: 93.8 KB
- Stars: 30
- Watchers: 4
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ddtrace-asgi
[](https://dev.azure.com/florimondmanca/public/_build/latest?definitionId=2&branchName=master)
[](https://codecov.io/gh/florimondmanca/ddtrace-asgi)
[](https://pypi.org/project/ddtrace-asgi)
Unofficial `ddtrace` integration for ASGI apps and frameworks.
Should work seamlessly for any ASGI web framework, e.g. Starlette, FastAPI, Quart, etc.
**Note**: This project is in alpha stage.
## Requirements
- Python 3.6+.
- [`ddtrace`](https://github.com/DataDog/dd-trace-py) must be installed to use the `ddtrace-run` command.
- The [Datadog Agent](https://docs.datadoghq.com/agent/) must be installed and running for traces to be effectively sent to Datadog APM.
## Installation
```bash
pip install ddtrace-asgi
```
## Quickstart
To automatically send traces to [Datadog APM](https://docs.datadoghq.com/tracing/) on each HTTP request, wrap your ASGI application around `TraceMiddleware`:
```python
# app.py
from ddtrace_asgi import TraceMiddleware
async def app(scope, receive, send):
assert scope["type"] == "http"
headers = [[b"content-type", b"text/plain"]]
await send({"type": "http.response.start", "status": 200, "headers": headers})
await send({"type": "http.response.body", "body": b"Hello, world!"})
app = TraceMiddleware(app)
```
Then use `ddtrace-run` when serving your application. For example, if serving with Uvicorn:
```bash
ddtrace-run uvicorn app:app
```
For more information on using `ddtrace`, please see the official [`dd-trace-py`](https://github.com/DataDog/dd-trace-py) repository.
## Examples
### Starlette
```python
from ddtrace_asgi import TraceMiddleware
from starlette.applications import Starlette
app = Starlette()
app.add_middleware(TraceMiddleware, service="my-starlette-app")
```
### FastAPI
```python
from ddtrace_asgi import TraceMiddleware
from fastapi import FastAPI
app = FastAPI()
app.add_middleware(TraceMiddleware, service="my-fastapi-app")
```
## API Reference
### `TracingMiddleware`
```python
class TracingMiddleware:
def __init__(self, app, tracer=None, service="asgi", tags=None, distributed_tracing=True):
...
```
An ASGI middleware that sends traces of HTTP requests to Datadog APM.
**Parameters**
- **app** - An [ASGI](https://asgi.readthedocs.io) application.
- **tracer** - _(optional)_ A [`Tracer`](http://pypi.datadoghq.com/trace/docs/advanced_usage.html#tracer) object. Defaults to the global `ddtrace.tracer` object.
- **service** - _(optional)_ Name of the service as it will appear on Datadog.
- **tags** - _(optional)_ Constant tags to apply to all traces. Either a dictionary, or a list of `":"` strings. See also [Tagging](https://docs.datadoghq.com/tagging/).
- **distributed_tracing** - _(optional)_ Whether to enable [distributed tracing](http://pypi.datadoghq.com/trace/docs/advanced_usage.html#distributed-tracing).