OpenAI Integration
Drop-in wrapper for the OpenAI SDK. Change one import and every GPT-4o, GPT-4, and o-series call is automatically traced in Zespan.
OpenAI provides the GPT-4o, GPT-4, and o-series models via API, used for chat completion, embeddings, function calling, and structured output.
Getting Started
Install the SDK
Install @zespan/sdk alongside your existing OpenAI SDK.
npm install @zespan/sdk openaiWrap the OpenAI client
Pass your OpenAI client to wrapOpenAI(). All calls made through the wrapped client are traced automatically — no other changes required.
import OpenAI from 'openai';
import { Zespan, wrapOpenAI } from '@zespan/sdk';
const lt = new Zespan({ apiKey: process.env.ZESPAN_API_KEY });
const openai = wrapOpenAI(new OpenAI(), lt);
// All calls now traced — tokens, cost, latency, errors
const res = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello' }],
});View traces in Zespan
Open Trace Explorer in Zespan. Your OpenAI calls appear as traces with model, token counts, USD cost, latency, and any errors.
What's captured automatically
- Token usage: input and output tokens per call
- USD cost: per call, per model, per agent, per user
- Latency: time-to-first-token and total latency
- Function calls and tool use: captured as child spans
- API errors: rate limits, timeouts, content policy blocks — full context
- Structured output: JSON schema compliance visible per response
FAQ
Does wrapOpenAI() add latency to my requests?
No. Traces are sent asynchronously in the background. wrapOpenAI() adds zero latency to the OpenAI API call itself.
Does this work with Azure OpenAI?
Yes. wrapOpenAI() works with both the standard OpenAI SDK and the Azure OpenAI client. Pass your Azure client the same way.
Can I track which user or agent made each call?
Yes. Pass session_id, user_id, and agent_name in the metadata options on any call. These appear in the Trace Explorer as filterable attributes.
What happens if the Zespan API is unavailable?
LLM calls proceed normally. Trace events are queued locally; if the API is unreachable, traces are dropped rather than blocking your application.
Start for free — 10K traces/month, no card needed
OpenAI integration works on all plans including the free tier.