# DevStream

> DevStream is a self-hosted logging service. Applications send log messages —
> with optional name/value tags and an optional structured JSON `data` object —
> over HTTP, then view and stream them in real time. This document describes how
> to integrate with DevStream, for both humans and AI coding agents.

Base URL: https://devstream.fly.dev

## Python client (recommended for Python projects)

Install:

```
pip install devstream-client
```

Send logs:

```python
from devstream_client import DevStreamClient

client = DevStreamClient(
    api_key="<your-api-key>",
    app_key="<your-app-key>",
    deployment_key="prod",        # environment: e.g. local, dev, staging, prod
    base_url="https://devstream.fly.dev",
)

# simple message
client.log("Service started")

# message with tags (name/value pairs, used for filtering and search)
client.log_with_tags("User logged in", user_id="123", level="info")

# message with structured JSON data
client.log("Order placed", data={"order_id": 4823, "total": 19.99})
```

Standard library logging integration:

```python
import logging
from devstream_client import DevStreamHandler

handler = DevStreamHandler(
    api_key="<your-api-key>",
    app_key="<your-app-key>",
    deployment_key="prod",
    base_url="https://devstream.fly.dev",
)
logging.getLogger("myapp").addHandler(handler)
```

Client API summary:

- `DevStreamClient(api_key, app_key, deployment_key, base_url="http://localhost:8787", timeout=5.0, max_retries=2)`
- `client.log(message, tags=None, data=None) -> bool` — `tags` is a list of `{"name": str, "value": str}`; `data` is any JSON-serializable dict.
- `client.log_with_tags(message, data=None, **tags) -> bool` — tags given as keyword args, e.g. `level="info"`.
- `DevStreamHandler(api_key, app_key, deployment_key, base_url=..., extra_tags=None)` — a `logging.Handler` subclass.
- `devstream_logger(name, api_key, app_key, deployment_key, base_url=..., level=logging.INFO) -> logging.Logger`

Behavior: send methods never raise — on failure they return `False` and emit a
warning via the `devstream_client` logger, so logging can never break the host
application. Transient connection/5xx errors are retried automatically.

## Raw HTTP API (any language)

Ingest a log message:

```
POST https://devstream.fly.dev/api/logs/ingest
Content-Type: application/json
X-API-Key: <your-api-key>

{
  "api_key": "<your-api-key>",
  "app_key": "<your-app-key>",
  "deployment_key": "prod",
  "message": "Order placed",
  "tags": [{"name": "level", "value": "info"}],
  "data": {"order_id": 4823, "total": 19.99}
}
```

The API key may be sent in the `X-API-Key` header or in the JSON body. `tags`
and `data` are optional. A successful ingest returns HTTP 200.

curl example:

```
curl -X POST https://devstream.fly.dev/api/logs/ingest \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"app_key":"<your-app-key>","deployment_key":"prod","message":"hello","data":{"k":"v"}}'
```

## Concepts

- Application: identified by `app_key`, authenticated by `api_key`.
- Deployment: an environment under an application (`deployment_key`); created automatically on the first log it receives.
- Tags: name/value pairs attached to a message, used for filtering and search.
- Data: an arbitrary JSON object attached to a message.

## Links

- PyPI package: https://pypi.org/project/devstream-client/
- Source code: https://github.com/paul-wolf/devstream
- OpenAPI spec: https://devstream.fly.dev/api/openapi.json
- Interactive API docs: https://devstream.fly.dev/api/docs