amlexia

Official Python SDK for Amlexia. Monitor APIs, AI calls, and webhooks from FastAPI, Flask, Django, or plain Python.

pip install amlexia

License: Proprietary — not open source. See LICENSE.
Support: support@amlexia.com

Table of contents

• Installation
• Quick start
• AmlexiaClient
• track() parameters
• Environment variables
• FastAPI
• Flask
• Django
• Distributed tracing
• Provider detection
• Errors and retries
• Best practices

Cross-SDK docs: Environment variables · Event fields

Installation

pip install amlexia

Optional extras:

pip install "amlexia[fastapi]"
pip install "amlexia[flask]"

Quick start

import os
from amlexia import AmlexiaClient

client = AmlexiaClient(
    sdk_key=os.environ["AMLEXIA_SDK_KEY"],
    ingest_url=os.environ.get("AMLEXIA_INGEST_URL", "https://ingest.amlexia.com"),
)

client.track(
    endpoint="GET /health",
    method="GET",
    status_code=200,
    latency_ms=12,
)

client.shutdown()

From environment

from amlexia import AmlexiaClient

client = AmlexiaClient.from_env()
# Reads: AMLEXIA_SDK_KEY, AMLEXIA_INGEST_URL, AMLEXIA_ENVIRONMENT, AMLEXIA_RELEASE

AmlexiaClient

Constructor

AmlexiaClient(
    sdk_key: str,                          # Required
    ingest_url: str | None = None,         # Default: https://ingest.amlexia.com
    flush_interval_seconds: float = 5.0,   # Background flush interval
    max_batch_size: int = 50,              # Flush when buffer reaches this size
    max_retries: int = 5,                  # Retries per batch
    environment: str | None = None,        # Applied to every event
    release_version: str | None = None,    # Applied to every event
)

Methods

track() parameters

Required

client.track(
    endpoint="POST /v1/chat",
    method="POST",
    status_code=200,
    latency_ms=430,
)

Optional

client.track(
    endpoint="POST /v1/chat",
    method="POST",
    status_code=200,
    latency_ms=430,
    timestamp=None,                    # Unix seconds; default: now
    request_size_bytes=1024,
    response_size_bytes=4096,
    cost_usd=0.002,
    provider="openai",                 # Auto-detected if omitted
    error_message=None,
    metadata={"plan": "pro"},
    trace_id="...",
    span_id="...",
    parent_span_id="...",
    session_id="sess_abc",
    user_id="user_123",
    service_name="api",
    operation_name="/v1/chat",
    model_name="gpt-4o",
    tokens_input=120,
    tokens_output=80,
    streaming_latency_ms=1200,
    first_token_latency_ms=180,
    cache_hit=False,
    retry_count=0,
    is_webhook=False,
)

Python auto-sets provider_category, provider_name, and total_tokens when detection/token fields apply.

Full reference: Event fields.

Environment variables

See ENVIRONMENT_VARIABLES.md.

FastAPI

from fastapi import FastAPI
from amlexia import AmlexiaClient
from amlexia.fastapi_integration import AmlexiaMiddleware

client = AmlexiaClient.from_env()
app = FastAPI()
app.add_middleware(AmlexiaMiddleware, client=client, service_name="api")

@app.get("/users/{user_id}")
async def get_user(user_id: str):
    return {"user_id": user_id}

Middleware parameters

Behavior

• Wraps each request with trace + span
• Sets traceparent response header
• Normalizes paths (/users/42 → /users/:id)
• Detects provider from path
• Tracks status, latency, errors

Session / user headers

Flask

Decorator-based tracking per route:

from flask import Flask
from amlexia import AmlexiaClient
from amlexia.flask_integration import amlexia_track

client = AmlexiaClient.from_env()
app = Flask(__name__)

@app.get("/users/<int:user_id>")
@amlexia_track(client)
def get_user(user_id: int):
    return {"user_id": user_id}

On exception, records status_code=500 and error_message. Paths are normalized to /:id segments.

Django

Add middleware after SecurityMiddleware:

# settings.py
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "amlexia.django_integration.AmlexiaMiddleware",
    # ...
]

Environment:

AMLEXIA_SDK_KEY=am_...
AMLEXIA_INGEST_URL=https://ingest.amlexia.com   # optional
AMLEXIA_SERVICE_NAME=api                         # optional, default api

AmlexiaMiddleware uses AmlexiaClient.from_env() when no client is injected.

Optional headers: HTTP_X_SESSION_ID, HTTP_X_USER_ID (Django META format).

Distributed tracing

from amlexia.tracing import create_trace_context, child_span

trace = create_trace_context(
    session_id="sess_1",
    user_id="user_1",
    environment="production",
    release_version="1.4.0",
)
span = child_span(trace)

client.track(
    endpoint="POST /internal/job",
    method="POST",
    status_code=200,
    latency_ms=100,
    trace_id=span.trace_id,
    span_id=span.span_id,
    parent_span_id=span.parent_span_id,
    session_id=trace.session_id,
    user_id=trace.user_id,
)

Provider detection

If provider is omitted, the SDK inspects endpoint and metadata for known hosts (OpenAI, Anthropic, Stripe, Clerk, etc.) and sets:

• provider / provider_name
• provider_category
• model_name when inferrable

Override with explicit provider= when needed.

Errors and retries

Best practices

1. Singleton client per worker process (Gunicorn/Uvicorn).
2. Call shutdown() on worker exit hooks.
3. Prefer middleware for web frameworks — consistent paths and traces.
4. Use from_env() in production for twelve-factor config.
5. Do not log SDK keys or send them from client-side Python in untrusted environments.
6. Keep metadata small — avoid PII and secrets.

Module reference

Links

• Getting started
• Dashboard
• Terms · Privacy