> ## Documentation Index
> Fetch the complete documentation index at: https://arizeai-433a7140.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeSafe AI Tracing (TypeScript)

> Instrument TypeSafe AI SDK calls in TypeScript/Node.js

<Note>Looking for Python? See the [Python guide](/docs/phoenix/integrations/llm-providers/typesafe/typesafe-python).</Note>

[![NPM Version](https://img.shields.io/npm/v/@arizeai%2Fopeninference-instrumentation-typesafe.svg)](https://www.npmjs.com/package/@arizeai/openinference-instrumentation-typesafe)

This module provides [OpenInference](https://github.com/Arize-ai/openinference) instrumentation for the [TypeSafe AI Node.js SDK](https://www.npmjs.com/package/@typesafe-ai/sdk) (`@typesafe-ai/sdk`). Each `TypeSafeClient.systemOne` call is captured as an OpenInference `LLM` span with JSON `input.value` / `output.value`, model, and token usage.

Requires Node.js 20+. `client.models.list()` is not instrumented.

## Install

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm install --save @arizeai/phoenix-otel @arizeai/openinference-instrumentation-typesafe @typesafe-ai/sdk
```

## Setup

Use the `register` function from `@arizeai/phoenix-otel` to connect to Phoenix, then register the TypeSafe instrumentation.

Create the `instrumentation.ts` file:

```typescript expandable theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { register } from "@arizeai/phoenix-otel";
import { TypeSafeInstrumentation } from "@arizeai/openinference-instrumentation-typesafe";

// Initialize Phoenix tracing
export const provider = register({
  projectName: "typesafe-app",
  // If Phoenix is running elsewhere:
  // url: "https://your-phoenix.example.com",
  // apiKey: process.env.PHOENIX_API_KEY,
  // If using self-hosted Phoenix:
  // url: "http://localhost:6006",
});

// Set up TypeSafe SDK instrumentation
const instrumentation = new TypeSafeInstrumentation({
  tracerProvider: provider,
});
```

<Note>
  Registering the instrumentation this way patches `@typesafe-ai/sdk` at load time, which requires `instrumentation.ts` to run **before** the SDK is imported (CommonJS only). For ESM, bundlers, or when the SDK is imported first, call `manuallyInstrument` instead:

  ```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import * as TypeSafe from "@typesafe-ai/sdk";
  import { TypeSafeInstrumentation } from "@arizeai/openinference-instrumentation-typesafe";

  const instrumentation = new TypeSafeInstrumentation({ tracerProvider: provider });
  instrumentation.manuallyInstrument(TypeSafe);
  ```
</Note>

## Usage

```typescript expandable theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import "./instrumentation.js";
import { TypeSafeClient, choice } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();
const { data, requestId } = await client
  .systemOne({
    state: { document: "I was charged twice. Please fix this ASAP." },
    questions: {
      category: choice("What is this ticket about?", {
        billing: null,
        technical: null,
        other: null,
      }),
    },
  })
  .withResponse();

console.log(data.answers.category, requestId);
```

<Note>
  Spans are exported in batches. In short-lived scripts, call `await provider.forceFlush()` before the process exits so all spans are delivered to Phoenix.
</Note>

## Observe

With instrumentation enabled, each `systemOne` call shows up in Phoenix as an **LLM span** containing:

* The full `state` and `questions` sent to TypeSafe as `input.value` (JSON)
* The typed `answers` returned as `output.value` (JSON)
* Model name and token usage, when reported by the SDK

<Frame>
  <img src="https://storage.googleapis.com/arize-phoenix-assets/assets/images/typesafe.png" alt="TypeSafe AI traces in Phoenix" />
</Frame>

## Configuration

Pass `traceConfig` to mask sensitive request/response payloads before they leave your process:

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const instrumentation = new TypeSafeInstrumentation({
  tracerProvider: provider,
  traceConfig: {
    hideInputs: true,
    hideOutputs: true,
  },
});
```

See the [package README](https://github.com/Arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-typesafe) for the full list of `traceConfig` masking options and the SDK compatibility table.

## Resources

* [NPM Package](https://www.npmjs.com/package/@arizeai/openinference-instrumentation-typesafe)

* [Runnable examples](https://github.com/Arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-typesafe/examples)

* [TypeSafe AI SDK on npm](https://www.npmjs.com/package/@typesafe-ai/sdk)

* [TypeSafe AI Documentation](https://docs.typesafe.ai/)