Python SDK - Tracelit

Requirements: Python ≥ 3.10

Installation

pip install tracelit

Install OpenTelemetry instrumentation packages for your stack (see each tab below). Missing packages are skipped silently at startup.

Which setup do I use?

There is no tracelit.init() API.

App type	How to initialize Tracelit
Django	Add `tracelit.integrations.django.TracelitConfig` to `INSTALLED_APPS`. Do not call `auto_start()` in `settings.py`.
Flask	Call `tracelit.auto_start()` in `app.py` before routes run. Expose a module-level `app` object.
FastAPI	Call `tracelit.auto_start()` in `main.py` before the app serves traffic.
Celery worker	Call `install_celery_hook()` in `celery.py`.
Script / CLI / batch job	Call `tracelit.auto_start()` at process startup.

Framework setup

Django
Flask
FastAPI
Scripts / CLI

Add Tracelit to INSTALLED_APPS

Use the full app config class — not tracelit.integrations.django alone.

settings.py

INSTALLED_APPS = [
    "tracelit.integrations.django.TracelitConfig",
    "django.contrib.admin",
    # ...
]

Tracelit calls auto_start() in AppConfig.ready() after Django is fully configured. Do not call tracelit.auto_start() yourself in settings.py.

Set environment variables

.env

TRACELIT_API_KEY=your-api-key
TRACELIT_SERVICE_NAME=payments-api
TRACELIT_ENVIRONMENT=production
TRACELIT_ENDPOINT=https://ingest.tracelit.app

Install Django instrumentation

pip install opentelemetry-instrumentation-django

Restart and verify

python manage.py runserver

Hit any endpoint and confirm traces appear in the Tracelit dashboard.

python-decouple / django-environ

Bridge secrets into os.environ before INSTALLED_APPS:

settings.py

import os
from decouple import config

os.environ.setdefault("TRACELIT_API_KEY", config("TRACELIT_API_KEY"))
os.environ.setdefault("TRACELIT_SERVICE_NAME", config("TRACELIT_SERVICE_NAME", default="backend"))
os.environ.setdefault("TRACELIT_ENVIRONMENT", config("TRACELIT_ENVIRONMENT", default="production"))
os.environ.setdefault("TRACELIT_ENDPOINT", config("TRACELIT_ENDPOINT", default="https://ingest.tracelit.app"))

Celery workers

Web server instrumentation does not cover Celery. Add to celery.py:

celery.py

from tracelit.integrations.celery import install_celery_hook

install_celery_hook()

pip install opentelemetry-instrumentation-celery

Create app.py with Tracelit initialized first

app.py

import os

import tracelit

tracelit.auto_start(
    api_key=os.environ["TRACELIT_API_KEY"],
    service_name="my-flask-app",
    environment=os.getenv("FLASK_ENV", "production"),
)

from flask import Flask
from tracelit.integrations.wsgi import TracelitWSGIMiddleware

app = Flask(__name__)
app.wsgi_app = TracelitWSGIMiddleware(app.wsgi_app)


@app.get("/")
def home():
    return "ok"

FLASK_APP=app.py requires a module-level variable named app. If you use an app factory, use FLASK_APP=app:create_app instead.

Install Flask instrumentation

pip install opentelemetry-instrumentation-flask opentelemetry-instrumentation-wsgi

Run

export TRACELIT_API_KEY=your-api-key
FLASK_APP=app.py flask run

TracelitWSGIMiddleware records HTTP request metrics. Flask route tracing comes from opentelemetry-instrumentation-flask.

Create main.py

main.py

import os

import tracelit

tracelit.auto_start(
    api_key=os.environ["TRACELIT_API_KEY"],
    service_name="my-api",
    environment=os.getenv("ENV", "production"),
)

from fastapi import FastAPI
from tracelit.integrations.asgi import TracelitASGIMiddleware

app = FastAPI()
app = TracelitASGIMiddleware(app)


@app.get("/")
def home():
    return {"ok": True}

Install FastAPI instrumentation

pip install opentelemetry-instrumentation-fastapi opentelemetry-instrumentation-asgi

Run

export TRACELIT_API_KEY=your-api-key
uvicorn main:app

Use tracelit.auto_start() for batch jobs, cron tasks, and CLIs — not for Django.

worker.py

import os
import tracelit

tracelit.auto_start(
    api_key=os.environ["TRACELIT_API_KEY"],
    service_name="nightly-report",
    environment=os.getenv("ENV", "production"),
)

with tracelit.tracer().start_as_current_span("generate-report"):
    # your logic
    pass

Or rely on environment variables only:

import tracelit
tracelit.auto_start()

Configuration reference

All options can be passed to tracelit.auto_start(...) or set via environment variables.

Option	Env variable	Default	Description
`api_key`	`TRACELIT_API_KEY`	—	Required. Your Tracelit ingest API key
`service_name`	`TRACELIT_SERVICE_NAME`	`unknown-service`	Service name shown in Tracelit
`environment`	`TRACELIT_ENVIRONMENT`	`"production"`	Deployment environment tag
`endpoint`	`TRACELIT_ENDPOINT`	`https://ingest.tracelit.app`	Override only when self-hosting
`sample_rate`	`TRACELIT_SAMPLE_RATE`	`1.0`	Sampling ratio `0.0`–`1.0`. Errors always export.
`enabled`	`TRACELIT_ENABLED`	`true`	Set `false` to disable all telemetry in tests

Custom resource attributes

import tracelit

tracelit.auto_start(
    api_key="...",
    service_name="orders-api",
    resource_attributes={
        "deployment.region": "us-east-1",
        "team": "platform",
    },
)

Instrumentation packages

Tracelit instruments libraries only when the matching opentelemetry-instrumentation-* package is installed. Uninstalled packages are skipped silently — no startup warning spam.

Library	Package to install
Django	`opentelemetry-instrumentation-django`
Flask	`opentelemetry-instrumentation-flask`
FastAPI	`opentelemetry-instrumentation-fastapi`
PostgreSQL (psycopg2)	`opentelemetry-instrumentation-psycopg2`
MySQL	`opentelemetry-instrumentation-pymysql` or `opentelemetry-instrumentation-mysqlclient`
Redis	`opentelemetry-instrumentation-redis`
Celery	`opentelemetry-instrumentation-celery`
HTTP clients	`opentelemetry-instrumentation-requests`, `opentelemetry-instrumentation-httpx`

Disable specific instrumentations:

OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=sqlite3,asyncio,logging

Tracing

Manual spans

import tracelit

with tracelit.tracer().start_as_current_span("process_payment") as span:
    span.set_attribute("payment.id", payment_id)
    span.set_attribute("payment.amount", amount)
    process(payment)

Metrics

import tracelit

counter = tracelit.metrics.counter("orders.created", unit="{order}")
counter.add(1, {"plan": "pro"})

TracelitASGIMiddleware and TracelitWSGIMiddleware also record http.server.request.count, http.server.request.duration, and http.server.error.count per route.

Disabling in tests

TRACELIT_ENABLED=false pytest

Common mistakes

Calling tracelit.init()

This function does not exist. Use tracelit.auto_start() for Flask/FastAPI/scripts, or TracelitConfig for Django.

Calling auto_start() at the top of settings.py (Django)

Django is not ready yet. Use tracelit.integrations.django.TracelitConfig in INSTALLED_APPS instead.

FLASK_APP=app.py but Flask can't find the application

Flask expects a module-level variable named app. If you use a factory, set FLASK_APP=app:create_app.

Only installing tracelit without instrumentation packages

The SDK starts but won’t trace Django/Flask/Redis/etc. Install the matching opentelemetry-instrumentation-* packages.

Expecting Celery tasks to be traced from the web process

Workers are separate processes. Call install_celery_hook() in celery.py.

Source

github.com/Tracelit-AI/tracelit-python

​Installation

​Which setup do I use?

​Framework setup

​python-decouple / django-environ

​Celery workers

​Configuration reference

​Custom resource attributes

​Instrumentation packages

​Tracing

​Manual spans

​Metrics

​Disabling in tests

​Common mistakes

​Source

Installation

Which setup do I use?

Framework setup

python-decouple / django-environ

Celery workers

Configuration reference

Custom resource attributes

Instrumentation packages

Tracing

Manual spans

Metrics

Disabling in tests

Common mistakes

Source