Codex SDK (tracing) | Respan Docs

The OpenAI Codex SDK (@openai/codex-sdk) lets TypeScript applications start Codex threads and run coding-agent turns programmatically. Use @respan/instrumentation-codex-sdk to send Codex turn activity through the Respan tracing pipeline.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Use Respan Gateway

See Codex SDK gateway setup to route Codex SDK model calls through the Respan gateway.

Example projects

TypeScript examples

Setup

Install packages

$ npm install @openai/codex-sdk @respan/respan @respan/tracing @respan/instrumentation-codex-sdk

Set environment variables

$ export CODEX_API_KEY="YOUR_CODEX_OR_OPENAI_API_KEY"
$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

Initialize and run

1 import * as CodexSDKModule from "@openai/codex-sdk";
2 import { Codex } from "@openai/codex-sdk";
3 import { Respan } from "@respan/respan";
4 import { CodexSDKInstrumentor } from "@respan/instrumentation-codex-sdk";
5 
6 const respan = new Respan({
7   apiKey: process.env.RESPAN_API_KEY,
8   baseURL: process.env.RESPAN_BASE_URL,
9   appName: "codex-sdk-tracing",
10   instrumentations: [
11     new CodexSDKInstrumentor({
12       sdkModule: CodexSDKModule,
13       workflowName: "codex-sdk-tracing",
14       agentName: "codex-agent",
15     }),
16   ],
17 });
18 await respan.initialize();
19 
20 const codex = new Codex({
21   apiKey: process.env.CODEX_API_KEY ?? process.env.OPENAI_API_KEY,
22 });
23 
24 const thread = codex.startThread({
25   workingDirectory: process.cwd(),
26   skipGitRepoCheck: true,
27   sandboxMode: "read-only",
28   approvalPolicy: "never",
29 });
30 
31 const result = await respan.withWorkflow({ name: "codex-sdk-basic-turn" }, async () =>
32   await thread.run("Reply with one short sentence that explains tracing.")
33 );
34 
35 console.log(result.finalResponse);
36 await respan.shutdown();

Pass sdkModule when your app imports @openai/codex-sdk directly. This ensures the instrumentor patches the same SDK module instance your application uses.

View your trace

Open the Traces page to see Codex SDK turns with agent messages, reasoning, command execution, MCP tool calls, file changes, and errors.

Captured data

Data	Description
Buffered turns	`Thread.run()` calls and final responses.
Streamed turns	`Thread.runStreamed()` events and completed agent messages.
Reasoning	Reasoning summaries emitted by Codex.
Command execution	Shell command events and results.
MCP tool calls	MCP tool invocation events from Codex turns.
Web search	Web search events when enabled in Codex options.
File changes	File change events produced by Codex.
Structured output	Output schema usage and final structured responses.
Failures	Failed turns and stream errors with backend-visible error fields.

Attributes

Use Respan attributes to group Codex runs by user, thread, or workflow.

1 await respan.propagateAttributes(
2   {
3     customer_identifier: "user_123",
4     thread_identifier: "codex-thread-abc",
5     metadata: {
6       feature: "code-review",
7       environment: "production",
8     },
9   },
10   async () => {
11     await respan.withWorkflow({ name: "codex-review" }, async () => {
12       await thread.run("Review this change for correctness.");
13     });
14   }
15 );

Attribute	Type	Description
`customer_identifier`	`string`	Identifies the end user in Respan analytics.
`thread_identifier`	`string`	Groups related turns into a conversation.
`trace_group_identifier`	`string`	Groups related spans into a named trace group.
`metadata`	`object`	Custom key-value pairs attached to spans.