zoklens 2026.3.0

ZokLens Python SDK — LLM & Agent Observability via OpenTelemetry

ZokLens Python SDK

LLM & Agent Observability via OpenTelemetry. Track every LLM call, agent step, and chain interaction with 3 lines of code.

Quick Start

pip install zoklens

import zoklens

# 1. Initialize
zoklens.init(
    api_key="zok_xxx",                    # from ZokLens Console → API Keys
    endpoint="https://api.zoklens.com",   # or your self-hosted URL
    project="my-agent",
)

# 2. Auto-instrument LLM SDKs (one line)
zoklens.instrument(providers=["openai", "anthropic"])

# 3. Your existing code — zero changes needed
import openai
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
# ✅ Trace automatically captured: model, tokens, cost, latency

Features

Auto-Instrumentation

Automatically patches LLM SDKs to capture traces — zero code changes to your LLM calls.

zoklens.instrument(providers=["openai"])        # OpenAI SDK
zoklens.instrument(providers=["anthropic"])      # Anthropic SDK
zoklens.instrument(providers=["deepseek"])       # DeepSeek (OpenAI-compatible)

Captured attributes: llm.model, llm.provider, llm.tokens.input, llm.tokens.output, llm.cost.usd, llm.duration_ms

Custom Spans

Track any operation in your agent pipeline:

with zoklens.span("retrieval", metadata={"query": "cost trends", "top_k": 5}):
    docs = retriever.search(query)

with zoklens.span("generation", metadata={"model": "gpt-4o"}):
    response = llm.generate(prompt)

Session Tracking

Group related spans under a session with user context:

with zoklens.session(user_id="u123", session_id="s456"):
    # All spans inside automatically get user_id and session_id
    with zoklens.span("step-1"):
        ...
    with zoklens.span("step-2"):
        ...

Shutdown

Flush pending spans before exit:

zoklens.shutdown()

How It Works

Your App                          ZokLens
┌─────────────────────┐         ┌──────────────┐
│  import zoklens      │         │              │
│  zoklens.init(...)   │  OTLP  │  Trace Store │
│  zoklens.instrument()│────────→│  Cost Calc   │
│                      │  HTTP  │  AI Copilot  │
│  llm.chat(...)       │         │              │
└─────────────────────┘         └──────────────┘

The SDK uses OpenTelemetry under the hood:

• Configures a TracerProvider with a custom ZokLensSpanExporter
• Exports traces via OTLP/HTTP to POST /api/v1/otel/v1/traces
• Authenticates with X-API-Key header for tenant isolation

SDK vs Proxy

	Proxy (Sprint 10)	SDK (Sprint 12)
Setup	Change BASE_URL	import zoklens
Code changes	Zero	3 lines
Trace depth	HTTP layer	Span/chain level
Custom attributes	❌	✅ user_id, session, metadata
Agent internals	❌	✅ step/tool/chain tracking
Best for	Quick start	Agent developers

Both can be used simultaneously.

Requirements

• Python ≥ 3.9
• OpenTelemetry SDK (installed automatically)

License

Apache-2.0