> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install and configure Axiom AI SDK to begin capturing telemetry from your generative AI applications.

Quickly start capturing telemetry data from your generative AI capabilities. After installation and configuration, follow the Axiom AI engineering workflow to create, evaluate, observe, and iterate.

<Tip>
  This page explains how to set up instrumentation with Axiom AI SDK. Expand the section below to choose the right instrumentation approach for your needs.
</Tip>

<Accordion title="Choose your instrumentation approach">
  Axiom offers the following approaches to capture generative AI telemetry:

  | Instrumentation approach                                             | Language support | Characteristics                                              |
  | :------------------------------------------------------------------- | :--------------- | :----------------------------------------------------------- |
  | [Axiom AI SDK](/ai-engineering/observe/axiom-ai-sdk-instrumentation) | TypeScript       | Quick setup.<br />Minimal code changes.                      |
  | [Manual](/ai-engineering/observe/manual-instrumentation)             | Any              | More involved setup.<br />Full control over instrumentation. |

  **Instrumentation with Axiom AI SDK** is the right choice for you if you have a TypeScript app and you want the SDK to capture and send traces with the correct semantic conventions.

  **Manual instrumentation** is the right choice for you if you want to use your own tooling or if you use a language other than TypeScript. You need to instrument your app manually to emit traces compatible with Axiom’s AI engineering features.

  Both approaches emit identical attributes. This means that all the telemetry analysis features work the same way.
</Accordion>

## Prerequisites

* [Create an Axiom account](https://app.axiom.co/register).
* [Create a dataset in Axiom](/reference/datasets#create-dataset) where you send your data.
* [Create an API token in Axiom](/reference/tokens) with permissions to ingest data to the dataset you have created.

## Install

Install Axiom AI SDK into your TypeScript project:

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm i axiom
  ```

  ```bash npm theme={null}
  npm i axiom
  ```

  ```bash yarn theme={null}
  yarn add axiom
  ```

  ```bash bun theme={null}
  bun add axiom
  ```
</CodeGroup>

<Info>
  The `axiom` package includes the `axiom` command-line interface (CLI) for running evaluations, which you'll use to systematically test and improve your AI capabilities.
</Info>

## Configure tracer

To send data to Axiom, configure a tracer. For example, use a dedicated instrumentation file and load it before the rest of your app. An example configuration for a Node.js environment:

1. Install dependencies:

   <CodeGroup>
     ```bash pnpm theme={null}
     pnpm i \
       dotenv \
       @opentelemetry/exporter-trace-otlp-http \
       @opentelemetry/resources \
       @opentelemetry/sdk-trace-node \
       @opentelemetry/semantic-conventions \
       @opentelemetry/api
     ```

     ```bash npm theme={null}
     npm i \
       dotenv \
       @opentelemetry/exporter-trace-otlp-http \
       @opentelemetry/resources \
       @opentelemetry/sdk-trace-node \
       @opentelemetry/semantic-conventions \
       @opentelemetry/api
     ```

     ```bash yarn theme={null}
     yarn add \
       dotenv \
       @opentelemetry/exporter-trace-otlp-http \
       @opentelemetry/resources \
       @opentelemetry/sdk-trace-node \
       @opentelemetry/semantic-conventions \
       @opentelemetry/api
     ```

     ```bash bun theme={null}
     bun add \
       dotenv \
       @opentelemetry/exporter-trace-otlp-http \
       @opentelemetry/resources \
       @opentelemetry/sdk-trace-node \
       @opentelemetry/semantic-conventions \
       @opentelemetry/api
     ```
   </CodeGroup>

2. Create an instrumentation file:

   ```ts /src/instrumentation.ts expandable theme={null}
   import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
   import { resourceFromAttributes } from '@opentelemetry/resources';
   import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
   import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
   import { trace } from "@opentelemetry/api";
   import { initAxiomAI, RedactionPolicy } from 'axiom/ai';
   import type { AxiomEvalInstrumentationHook } from 'axiom/ai/config';

   const tracer = trace.getTracer("my-tracer");

   let provider: NodeTracerProvider | undefined;

   // Wrap your logic in the AxiomEvalInstrumentationHook function
   export const setupAppInstrumentation: AxiomEvalInstrumentationHook = async ({
     dataset,
     edgeUrl,
     token,
   }) => {
     if (provider) {
       return { provider };
     }

     if (!dataset || !edgeUrl || !token) {
       throw new Error('Missing environment variables');
     }

     const exporter = new OTLPTraceExporter({
       url: `${edgeUrl}/v1/traces`,
       headers: {
         Authorization: `Bearer ${token}`,
         'X-Axiom-Dataset': dataset,
       },
     })

     // Configure the provider to export traces to your Axiom dataset
     provider = new NodeTracerProvider({
       resource: resourceFromAttributes({
         [ATTR_SERVICE_NAME]: 'my-app', // Replace with your service name
       },
       {
         // Use the latest schema version
         // Info: https://opentelemetry.io/docs/specs/semconv/
         schemaUrl: 'https://opentelemetry.io/schemas/1.37.0',
       }),
       spanProcessors: [new BatchSpanProcessor(exporter)],
     });

     // Register the provider
     provider.register();

     // Initialize Axiom AI SDK with the configured tracer
     initAxiomAI({ tracer, redactionPolicy: RedactionPolicy.AxiomDefault });

     return { provider };
   };
   ```

For more information on specifying redaction policies, see [Redaction policies](/ai-engineering/redaction-policies).

### Create Axiom configuration file

The Axiom configuration file enables the evaluation framework, allowing you to run systematic tests against your AI capabilities and track improvements over time.

At the root of your project, create the Axiom configuration file `/axiom.config.ts`:

```ts /axiom.config.ts theme={null}
import { defineConfig } from 'axiom/ai/config';
import { setupAppInstrumentation } from './src/instrumentation';

export default defineConfig({
  eval: {
    edgeUrl: process.env.AXIOM_URL,
    token: process.env.AXIOM_TOKEN,
    dataset: process.env.AXIOM_DATASET,

    // Optional: customize which files to run
    include: ['**/*.eval.{ts,js}'],

    // Optional: exclude patterns
    exclude: [],

    // Optional: timeout for eval execution
    timeoutMs: 60_000,

    // Optional: instrumentation hook for OpenTelemetry
    // (created this in the "Create instrumentation setup" step)
    instrumentation: (options) => setupAppInstrumentation(options),
  },
});
```

## Store environment variables

Store environment variables in an `.env` file in the root of your project:

```bash .env theme={null}
AXIOM_URL="https://AXIOM_DOMAIN"
AXIOM_TOKEN="API_TOKEN"
AXIOM_DATASET="DATASET_NAME"
OPENAI_API_KEY=""
GEMINI_API_KEY=""
XAI_API_KEY=""
ANTHROPIC_API_KEY=""
```

<Info>
  Replace `API_TOKEN` with the Axiom API token you have generated. For added security, store the API token in an environment variable.

  Replace `DATASET_NAME` with the name of the Axiom dataset where you send your data.

  Replace `AXIOM_DOMAIN` with the base domain of your edge deployment. For more information, see [Edge deployments](/reference/edge-deployments).

  Enter the API keys for the LLMs you want to work with.
</Info>

<Note>
  To run offline evaluations, you can authenticate using OAuth instead of using environment variables. For more information, see [Set up and authenticate offline evaluations](/ai-engineering/evaluate/write-evaluations#prerequisites).
</Note>

## What’s next?

* **Build your first capability**: Start prototyping with [Create](/ai-engineering/create).
* **Set up evaluations**: Learn how to systematically test your capabilities with [Evaluate](/ai-engineering/evaluate/overview).
* **Capture production telemetry**: Instrument your AI calls for observability with [Observe](/ai-engineering/observe).