tracely-sdk 0.2.0

Lightweight observability SDK for Python web frameworks. Auto-instruments FastAPI, Flask, and Django with real-time tracing via OTLP/HTTP.

tracely-sdk

Lightweight observability SDK for Python web frameworks. Auto-instruments FastAPI, Flask, and Django with real-time distributed tracing via OTLP/HTTP.

Features

• Zero-config auto-instrumentation -- detects FastAPI, Flask, and Django automatically
• Real-time pending spans -- see requests the moment they start, not just when they finish
• Full request/response capture -- headers, body, query params with smart redaction
• OTLP/HTTP protobuf export -- standard OpenTelemetry wire format
• Batch export with backoff -- 1s flush interval, exponential retry on failure
• Fail-silent design -- SDK never crashes or degrades your application
• Minimal dependencies -- only httpx and opentelemetry-proto

Installation

pip install tracely-sdk

Quick Start

FastAPI

import tracely
from tracely.instrumentation.fastapi_inst import TracelyASGIMiddleware

tracely.init(api_key="trly_your_key_here")

from fastapi import FastAPI
app = FastAPI()
app.add_middleware(TracelyASGIMiddleware)

@app.get("/")
async def root():
    return {"status": "ok"}

Flask

import tracely
from tracely.instrumentation.flask_inst import FlaskInstrumentor

tracely.init(api_key="trly_your_key_here")

from flask import Flask
app = Flask(__name__)
app.wsgi_app = FlaskInstrumentor.wrap_app(app.wsgi_app)

@app.route("/")
def root():
    return {"status": "ok"}

Django

Add the middleware to your MIDDLEWARE setting:

# settings.py
MIDDLEWARE = [
    "tracely.instrumentation.django_inst.TracelyDjangoMiddleware",
    # ... other middleware
]

Then initialize in your app startup (e.g., AppConfig.ready()):

import tracely
tracely.init(api_key="trly_your_key_here")

Configuration

Environment Variables

Variable	Description	Default
TRACELY_API_KEY	API key for authentication	(required)
TRACELY_ENDPOINT	Ingestion API endpoint	https://i.tracely.sh
ENVIRONMENT	Deployment environment (e.g., production)	None
TRACELY_REDACT_FIELDS	Comma-separated header/field names to redact	None

Programmatic Init

import tracely

tracely.init(
    api_key="trly_your_key_here",
    environment="production",
    service_name="my-api",
    service_version="1.0.0",
)

Custom Spans

Create manual spans for custom operations:

import tracely

with tracely.span("db-query", kind="CLIENT") as s:
    s.set_attribute("db.system", "postgres")
    s.set_attribute("db.statement", "SELECT * FROM users")
    result = db.execute("SELECT * FROM users")

Span Events (Structured Logging)

Attach structured log events to the active span:

import tracely

with tracely.span("process-order") as s:
    tracely.info("Order received", order_id="123")
    # ... process
    tracely.debug("Validation passed")
    tracely.warning("Inventory low", sku="WIDGET-42")

Graceful Shutdown

Flush buffered spans before exit:

import tracely

tracely.init(api_key="trly_your_key_here")
# ... application runs ...
tracely.shutdown()  # flushes remaining spans

How It Works

Your App
  |
  v
Middleware (FastAPI/Flask/Django)
  |-- on_start --> SpanProcessor --> SpanBuffer (pending_span)
  |-- on_end ----> SpanProcessor --> SpanBuffer (final span)
                                        |
                                        v
                                  BatchSpanExporter (1s interval / 50 span threshold)
                                        |
                                        v
                                  OTLP Protobuf Serialization
                                        |
                                        v
                                  HttpTransport --> TRACELY API
                                  (retry with exponential backoff)

Documentation

Full docs at docs.tracely.sh

License

MIT