The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
---
title: "OpenAI"
description: "Instrument OpenAI SDK calls with Beacon Observe"
---
## Integration overview
Use this integration when your application calls the `openai` JavaScript package directly. Beacon Observe uses OpenLLMetry's OpenAI instrumentation so OpenAI spans flow through the same exporter and Beacon-compatible attribute path as the rest of your agent telemetry.
## Overview
Initialize Beacon Observe before creating the OpenAI client when possible. The instrumentation captures supported OpenAI SDK spans without changing the way you call `openai`.
## What Beacon captures
- OpenAI model calls emitted by the OpenLLMetry OpenAI instrumentation.
- OpenTelemetry resource attributes such as service name, SDK version, `beacon.origin=cloud`, and export mode.
- Beacon compatibility hints where supported by the SDK and instrumentation path.
- Errors recorded on failed spans.
## Prerequisites
- Node.js 20 or newer.
- `@asymptote/sdk` installed.
- `openai` installed.
- `ASYMPTOTE_API_KEY` set for Beacon Cloud hosted Observe, or `OTEL_EXPORTER_OTLP_ENDPOINT` set for customer-managed OTLP export. To get a Beacon Cloud API key, [reach out for a demo](https://asymptotelabs.ai/contact).
```bash title="Install the SDK and OpenAI client"
npm install @asymptote/sdk openai
```
Set environment variables:
```bash title="Set Beacon Cloud and OpenAI environment variables"
export ASYMPTOTE_API_KEY=...
export OPENAI_API_KEY=...
```
## Getting started
Initialize `Observe` before creating the OpenAI client when possible.
```typescript title="Trace OpenAI responses.create" lines
import OpenAI from "openai";
import { Observe } from "@asymptote/sdk";
Observe.initialize({
apiKey: process.env.ASYMPTOTE_API_KEY,
instrumentationOptions: {
openAI: {
traceContent: true,
},
},
});
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});
const response = await openai.responses.create({
model: "gpt-4.1-mini",
input: "Summarize the security implications of this diff.",
});
await Observe.flush();
```
All supported OpenAI SDK calls are now traced through the configured Beacon exporter.
## Already-loaded clients
If your application imports or creates the OpenAI client before initialization, pass the module to `instrumentModules` or patch it after initialization.
```typescript title="Instrument an already-loaded OpenAI module" lines
import OpenAI from "openai";
import { Observe } from "@asymptote/sdk";
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});
Observe.initialize({
apiKey: process.env.ASYMPTOTE_API_KEY,
instrumentModules: {
OpenAI,
},
});
const response = await openai.chat.completions.create({
model: "gpt-4.1-mini",
messages: [
{
role: "user",
content: "Draft a remediation plan for this finding.",
},
],
});
await Observe.flush();
```
## Group calls with custom spans
Wrap application logic with `Observe.observe()` when one route, job, or agent turn makes multiple OpenAI calls and you want them grouped under one parent span.
```typescript title="Wrap multiple OpenAI calls" lines
import OpenAI from "openai";
import { Observe } from "@asymptote/sdk";
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
});
const reviewPullRequest = Observe.observe(
{ name: "agent.pr_review" },
async (diff: string) => {
const summary = await openai.responses.create({
model: "gpt-4.1-mini",
input: `Summarize this diff:\n${diff}`,
});
const risk = await openai.responses.create({
model: "gpt-4.1-mini",
input: `Identify security risks in: ${summary.output_text}`,
});
return risk.output_text;
},
);
```
## Existing OpenTelemetry providers
If your application already owns OpenTelemetry setup, register Beacon's OpenAI instrumentation with your existing provider instead of calling `Observe.initialize()` twice.
```typescript title="Register OpenAI instrumentation on an existing provider" lines
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { Observe } from "@asymptote/sdk";
registerInstrumentations({
instrumentations: Observe.instrumentations({
openAI: {
traceContent: true,
},
anthropic: false,
}),
});
```
## Troubleshooting
- Confirm `ASYMPTOTE_API_KEY` or `OTEL_EXPORTER_OTLP_ENDPOINT` is set in the same process that runs the SDK.
- Initialize `Observe` before constructing the OpenAI client when possible.
- If the OpenAI module is imported before initialization, pass it through `instrumentModules` or `Observe.patch()`.
- Call `Observe.flush()` before short-lived scripts or jobs exit.
## What's next
<Columns cols={2}>
<Card title="Instrumentation" icon="wand-magic-sparkles" href="/sdk/instrumentation">
Review initialization, module patching, and existing OpenTelemetry provider setup.
</Card>
<Card title="Observe" icon="diagram-project" href="/sdk/observe">
Group multiple model calls and custom agent steps under parent spans.
</Card>
</Columns>