zespan-flask 1.0.0

Zespan observability middleware for Flask

zespan-flask

Automatic LLM observability middleware for Flask. Traces every request, LLM call, and custom span with zero code changes for basic usage.

Installation

pip install zespan-flask

Quick Start

from flask import Flask
from zespan_flask import ZespanFlaskExtension, ZespanConfig

app = Flask(__name__)

config = ZespanConfig(api_key="zsp_your_api_key")
lumiq = ZespanFlaskExtension(app, config)

Every HTTP request is now automatically traced.

Application Factory Pattern

lumiq = ZespanFlaskExtension()

def create_app():
    app = Flask(__name__)
    lumiq.init_app(app)
    return app

Trace LLM Calls

from zespan_flask import observe_llm

@observe_llm(model="gpt-4o", provider="openai")
def generate_response(prompt: str):
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )
    return response

Trace Custom Spans

from zespan_flask import observe_span

@observe_span("fetch_context", span_type="retrieval")
def fetch_context(query: str):
    return vector_db.search(query)

Set Custom Attributes

from zespan_flask import set_attribute

@app.route("/chat")
def chat():
    set_attribute("user.id", current_user.id)
    set_attribute("session.id", session.get("id"))

Configuration

Option	Default	Description
api_key	required	Zespan API key (zsp_...)
base_url	https://api.zespan.com	API endpoint
enabled	True	Toggle tracing on/off
sample_rate	1.0	Fraction of requests to trace (0.0–1.0)
capture_request_body	False	Include request body in traces
capture_response_body	False	Include response body in traces
redact_fields	["password","token","api_key"]	Fields redacted automatically
debug	False	Print flush errors to stdout

Get your API key at zespan.com.