# OpenAI

Trace every OpenAI client call with Rius without touching your call
sites.

## Setup

<Tabs items={['Python', 'TypeScript']} storageKey="sdk-language">
<Tabs.Tab>
```bash
pip install "glassflow-rius[openai]" openai
```

The extra installs the instrumentation, not `openai` itself, so the
package is named here for a fresh environment. A project that already
calls OpenAI has it, and pip leaves it untouched. Without it, `init()`
logs a `DependencyConflict` and this integration stays off.

```python
import rius
from openai import OpenAI

rius.init(api_key="ri_...", service_name="my-agent")
client = OpenAI()  # use the client exactly as before
```

`init()` detects the installed extra and instruments the client library
process-wide; every call from anywhere in your process is traced.
</Tabs.Tab>
<Tabs.Tab>
```bash
npm install @arizeai/openinference-instrumentation-openai
```

```typescript

const rius = init({ apiKey: 'ri_...', serviceName: 'my-agent' })
const client = new OpenAI()  // use the client exactly as before
```

`init()` enables the integration if the package above is installed, and
instruments the client library process-wide. Call it before you create the
client, so the patch is in place by the time you make a request. `await
rius.ready` resolves with the integrations that attached, so it tells you
whether `openai` is among them.

Works in CommonJS and pure-ESM applications alike: the SDK patches the
build of `openai` your process actually uses. One ordering rule for
CommonJS apps: require `openai` before `init()`. A require that only
happens after `init()` stays untraced even though `client.ready` lists
`openai`. See
[Troubleshooting](/rius/sdk/troubleshooting#an-instrumentation-is-not-producing-spans).

Deploying a pnpm app to a file-tracing host, such as a Vercel function? The
SDK may not find the package there, and `client.ready` then leaves out
`openai`. Pass the modules you import with `instrumentModules`; see
[pnpm and serverless deployments](/rius/sdk/integrations#pnpm-and-serverless-deployments).
</Tabs.Tab>
</Tabs>

## What gets captured

Each chat completion becomes an LLM-kind span carrying the model, token
usage, and input/output messages; cost is computed server-side from the
model and tokens. The SDK maps the keys the integration's package writes onto the canonical
GenAI ones, including the request parameters, finish reasons, the
completion id, and the tool definitions; see
[what the SDK normalizes](/rius/sdk/auto-instrumentation#what-the-sdk-normalizes).
On **streamed** calls the Python integration also records time to first
token, without any manual code.

A call OpenAI rejects, such as a 404 for an unknown model, a 429, or a
timeout, is recorded as an ERROR span with `error.type` naming the error
class (`openai.NotFoundError`, for example). In TypeScript this needs
`@arizeai/openinference-instrumentation-openai` 4.4.1 or newer, which ends a
rejected call's span itself; `@glassflow-ai/rius` 1.1.0 and later require
that version as their peer, so an older one gets a peer dependency warning.

## Streaming and token usage

Streamed responses do not include usage by default; ask OpenAI to send it
with the final chunk:

<Tabs items={['Python', 'TypeScript']} storageKey="sdk-language">
<Tabs.Tab>
```python
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    stream=True,
    stream_options={"include_usage": True},
)
```
</Tabs.Tab>
<Tabs.Tab>
```typescript
const stream = await client.chat.completions.create({
model: 'gpt-4o-mini',
messages,
stream: true,
stream_options: { include_usage: true },
})
```
</Tabs.Tab>
</Tabs>

Without it, streamed spans have no token counts, and no tokens means no
cost.

In TypeScript, streamed chat completions carry no time to first token:
the OpenInference OpenAI instrumentation for Node does not record it. They do carry token usage, and so a cost, when you set
`include_usage` as above. Where time to first token matters, trace the
streamed call as a
[manual generation](/rius/sdk/tracing#streaming-responses).

## Verify

Run one call, then open the trace in the console: the span shows the
resolved model (for example `gpt-4o-mini-2024-07-18`), input/output token counts,
and a cost. Wrap the call in [`observe`](/rius/sdk/tracing#tracing-functions-with-observe)
to see it nested inside your agent's run instead of as a standalone trace.

Prompt and response content is subject to your
[privacy controls](/rius/sdk/advanced#privacy-controls): `capture_content=False`
(`captureContent: false` in TypeScript) and masking apply to instrumented
calls exactly like manual ones.
