Metadata-Version: 2.1
Name: ddtrace-asgi
Version: 0.2.2
Summary: Unofficial ddtrace integration for ASGI apps and frameworks
Home-page: http://github.com/florimondmanca/ddtrace-asgi
Author: Florimond Manca
Author-email: florimond.manca@gmail.com
License: BSD
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: ddtrace
Requires-Dist: starlette (==0.*)

# ddtrace-asgi

[![Build Status](https://travis-ci.com/florimondmanca/ddtrace-asgi.svg?branch=master)](https://travis-ci.com/florimondmanca/ddtrace-asgi)
[![Coverage](https://codecov.io/gh/florimondmanca/ddtrace-asgi/branch/master/graph/badge.svg)](https://codecov.io/gh/florimondmanca/ddtrace-asgi)
[![Package version](https://badge.fury.io/py/ddtrace-asgi.svg)](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.

[`ddtrace`]: https://github.com/DataDog/dd-trace-py

**Note**: This project is in alpha stage.

## Requirements

- Python 3.6+.
- [`ddtrace`] 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.middleware 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, service="asgi-hello-world")
```

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 [`ddtrace`] repository.

## Examples

### Starlette

```python
from ddtrace_asgi.middleware import TraceMiddleware
from starlette.applications import Starlette

app = Starlette()
app.add_middleware(TraceMiddleware, service="my-starlette-app")
```

### FastAPI

```python
from ddtrace_asgi.middleware 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", distributed_tracing=True):
        ...
```

An ASGI middleware that sends traces of HTTP requests to Datadog APM.

**Parameters**

- **app** - An [ASGI] application.
- **tracer** - _(optional)_ A [`Tracer`] object. Defaults to the global `ddtrace.tracer` object.
- **service** - _(optional)_ Name of the service as it will appear on Datadog.
- **distributed_tracing** - _(optional)_ Whether to enable [distributed tracing].

[asgi]: https://asgi.readthedocs.io
[`tracer`]: http://pypi.datadoghq.com/trace/docs/advanced_usage.html#tracer
[distributed tracing]: http://pypi.datadoghq.com/trace/docs/advanced_usage.html#distributed-tracing


# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

## 0.2.2 - 2019-11-03

### Added

- Now ships with binary distribution (wheel) in addition to source distribution (sdist). (Pull #16)

## 0.2.1 - 2019-10-31

### Fixed

- Improve resilience to ASGI protocol violations. (Pull #11)

## 0.2.0 - 2019-10-30

### Changed

- The `tracer`, `service` and `distributed_tracing` parameters of `TraceMiddleware` are now keyword-only. (Pull #10)

### Added

- The `tracer` for `TraceMiddleware` is now the global `ddtrace.tracer` by default. (Pull #10)

## 0.1.0 - 2019-10-23

Initial release.

### Added

- Add `TracingMiddleware`.


