> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Azure OpenAI (tracing)

> Trace Azure OpenAI SDK calls with Respan in Python and TypeScript.

Trace calls made through the `openai` package's `AzureOpenAI` client. The instrumentation differs by language:

* **TypeScript** uses the dedicated `@respan/instrumentation-azure-openai` instrumentor. It also supports the legacy `@azure/openai` `OpenAIClient` when that package is present.
* **Python** has no separate Azure package. The `AzureOpenAI` client ships inside the `openai` package, so the OpenAI instrumentation (`respan-instrumentation-openai`) captures Azure OpenAI calls.

This tracing setup uses your Azure OpenAI credentials directly. To route requests through Respan instead, use the [Azure OpenAI gateway setup](/docs/integrations/gateway/azure-open-ai).

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

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

#### Use Respan Gateway

See [Azure OpenAI gateway setup](/docs/integrations/gateway/azure-open-ai) to route calls through the Respan gateway.

## Setup

#### Install packages

**`Python`**

```bash Python
pip install respan-ai respan-instrumentation-openai openai
```

**`TypeScript`**

```bash TypeScript
npm install @respan/respan @respan/instrumentation-azure-openai openai
```

Python has no dedicated Azure instrumentation package. The `respan-instrumentation-openai` `OpenAIInstrumentor` traces `AzureOpenAI` client calls because that client is part of the `openai` package.

#### Set environment variables

```bash
export AZURE_OPENAI_API_KEY="YOUR_AZURE_OPENAI_API_KEY"
export AZURE_OPENAI_ENDPOINT="https://YOUR_RESOURCE.openai.azure.com"
export OPENAI_API_VERSION="2024-10-21"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

`AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, and `OPENAI_API_VERSION` are used for Azure OpenAI requests. `RESPAN_API_KEY` exports traces to Respan.

#### Initialize and run

**`Python`**

```python Python
import os
from openai import AzureOpenAI
from respan import Respan
from respan_instrumentation_openai import OpenAIInstrumentor

respan = Respan(instrumentations=[OpenAIInstrumentor()])

client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.environ["OPENAI_API_VERSION"],
    azure_deployment="gpt-4o-mini",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)
```

**`TypeScript`**

```typescript TypeScript
import { AzureOpenAI } from "openai";
import * as OpenAI from "openai";
import { Respan } from "@respan/respan";
import { AzureOpenAIInstrumentor } from "@respan/instrumentation-azure-openai";

const respan = new Respan({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: process.env.RESPAN_BASE_URL,
  instrumentations: [
    new AzureOpenAIInstrumentor({ openAIModule: OpenAI }),
  ],
});
await respan.initialize();

const client = new AzureOpenAI({
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  endpoint: process.env.AZURE_OPENAI_ENDPOINT,
  apiVersion: process.env.OPENAI_API_VERSION,
  deployment: "gpt-4o-mini",
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(response.choices[0]?.message?.content);

await respan.shutdown();
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see Azure OpenAI chat, completion, embedding, and streaming spans.

## Configuration

The configuration, attributes, and captured-operations below describe the TypeScript `AzureOpenAIInstrumentor`. In Python, configuration lives on the OpenAI instrumentation — see the [OpenAI SDK tracing page](/docs/integrations/openai-sdk).

| Parameter           | Type                      | Default           | Description                                                                                       |
| ------------------- | ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `apiKey`            | `string \| undefined`     | `RESPAN_API_KEY`  | Respan API key used to export traces.                                                             |
| `baseURL`           | `string \| undefined`     | `RESPAN_BASE_URL` | Optional Respan trace export API URL.                                                             |
| `instrumentations`  | `RespanInstrumentation[]` | `[]`              | Include `new AzureOpenAIInstrumentor()` to activate Azure OpenAI tracing.                         |
| `openAIModule`      | `object \| undefined`     | dynamic import    | Pass the imported `openai` module when your app imports `AzureOpenAI` before initializing Respan. |
| `azureOpenAIModule` | `object \| undefined`     | dynamic import    | Optional legacy `@azure/openai` module for `OpenAIClient` applications.                           |
| `traceContent`      | `boolean`                 | `true`            | Capture prompt and completion content when spans are exported.                                    |

## Attributes

### With propagateAttributes

Override per-request attributes using a context scope.

```typescript
import { AzureOpenAI } from "openai";
import * as OpenAI from "openai";
import { Respan } from "@respan/respan";
import { AzureOpenAIInstrumentor } from "@respan/instrumentation-azure-openai";

const respan = new Respan({
  instrumentations: [
    new AzureOpenAIInstrumentor({ openAIModule: OpenAI }),
  ],
});
await respan.initialize();

const client = new AzureOpenAI({
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  endpoint: process.env.AZURE_OPENAI_ENDPOINT,
  apiVersion: process.env.OPENAI_API_VERSION,
  deployment: "gpt-4o-mini",
});

async function handleRequest(userId: string, question: string) {
  await respan.propagateAttributes(
    {
      customer_identifier: userId,
      thread_identifier: "conv_abc_123",
      metadata: { plan: "pro" },
    },
    async () => {
      const response = await client.chat.completions.create({
        model: "gpt-4o-mini",
        messages: [{ role: "user", content: question }],
      });
      console.log(response.choices[0]?.message?.content);
    }
  );
}
```

| Attribute             | Type                      | Description                                  |
| --------------------- | ------------------------- | -------------------------------------------- |
| `customer_identifier` | `string`                  | Identifies the end user in Respan analytics. |
| `thread_identifier`   | `string`                  | Groups related messages into a conversation. |
| `metadata`            | `Record<string, unknown>` | Custom key-value pairs.                      |

## Captured operations

* `AzureOpenAI.chat.completions.create()`
* `AzureOpenAI.completions.create()`
* `AzureOpenAI.embeddings.create()`
* Streaming chat and text completion calls
* Legacy `@azure/openai` `OpenAIClient` chat, completion, embedding, and streaming methods