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

# TypeScript SDK - Overview

The modular ABV TypeScript SDK is built on [**OpenTelemetry**](https://opentelemetry.io/) for robust observability, better context management, and easy integration with third-party libraries.

Official Link: [https://www.npmjs.com/package/@abvdev/core](https://www.npmjs.com/package/@abvdev/core)

# Quickstart

Get your first trace into ABV in just a few minutes.

## 1) Install packages

Install the relevant packages to get started with tracing:

```bash theme={null}
npm install @abvdev/tracing @abvdev/otel @opentelemetry/sdk-node
```

Learn more about the packages [here](./#packages).

## 2) Set up environment variables

Add your ABV credentials to your environment variables. Make sure that you have a `.env` file in your project root and a package like `dotenv` to load the variables.

```bash title=".env" theme={null}
ABV_API_KEY = "sk-abv-..."
ABV_BASE_URL = "https://app.abv.dev" # US region
# ABV_BASE_URL = "https://eu.app.abv.dev" # EU region
```

## 3) Set up OpenTelemetry

Create a file named `instrumentation.ts` to initialize the OpenTelemetry SDK. The `ABVSpanProcessor` is the key component that sends traces to ABV.

```typescript title="instrumentation.ts" theme={null}
import { NodeSDK } from "@opentelemetry/sdk-node";
import { ABVSpanProcessor } from "@abvdev/otel";

const sdk = new NodeSDK({
  spanProcessors: [new ABVSpanProcessor()],
});

sdk.start();
```

Modify `instrumentation.ts` file to use `dotenv` package to load the variables.

Additional parameters are provided to get traces visible in the UI immediately.

```bash theme={null}
npm install dotenv
```

```typescript title="instrumentation.ts" theme={null}
import dotenv from "dotenv";
dotenv.config();

import { NodeSDK } from "@opentelemetry/sdk-node";
import { ABVSpanProcessor } from "@abvdev/otel";

const sdk = new NodeSDK({
  spanProcessors: [
    new ABVSpanProcessor({
      apiKey: process.env.ABV_API_KEY,
      baseUrl: process.env.ABV_BASE_URL,
      exportMode: "immediate",
      flushAt: 1,
      flushInterval: 1,
      additionalHeaders: {
        "Content-Type": "application/json",
        "Accept": "application/json"
      }
    })
  ],
});

sdk.start();
```

Import the `instrumentation.ts` file at the very top of your application's entry point (e.g., `index.ts`).

```typescript title="index.ts" theme={null}
import "./instrumentation"; // Must be the first import
```

Learn more about setting up OpenTelemetry [here](/developer/sdks/js-ts/setup).

## 4) Instrument your application

Use one of the native ABV framework [integrations](/developer/sdks/js-ts/instrumentation) to automatically trace your application.

Alternatively, manually instrument your application, e.g. by using the `startActiveObservation`. This function takes a callback and automatically manages the observation's lifecycle and the OpenTelemetry context. Any observation created inside the callback will automatically be nested under the active observation, and the observation will be ended when the callback finishes.

This is just an example, check out the [instrumentation](/developer/sdks/js-ts/instrumentation) page for more details.

```typescript title="index.ts" theme={null}
import "./instrumentation";
import { startActiveObservation } from "@abvdev/tracing";

async function main() {
  await startActiveObservation("my-first-trace", async (span) => {
    span.update({
      input: "Hello, ABV!",
      output: "This is my first trace!",
    });
  });
}

main();
```

## 5) Run your application

Execute your application. You should see your trace appear in the ABV UI.

```bash theme={null}
npx tsx index.ts
```

# Packages

The ABV SDK is designed to be modular. Here's an overview of the available packages:

| Package           | Description                                                            | Environment  |
| ----------------- | ---------------------------------------------------------------------- | ------------ |
| `@abvdev/core`    | Core utilities, types, and logger shared across packages.              | Universal JS |
| `@abvdev/client`  | Client for features like prompts, datasets, and scores.                | Universal JS |
| `@abvdev/tracing` | Core OpenTelemetry-based tracing functions (`startObservation`, etc.). | Universal JS |
| `@abvdev/otel`    | The `ABVSpanProcessor` to export traces to ABV.                        | Node.js ≥ 20 |

# OpenTelemetry foundation

Building on OpenTelemetry is a core design choice for this SDK. It offers several key advantages:

* **Standardization**: It aligns with the industry standard for observability, making it easier to integrate with existing monitoring and APM tools.
* **Robust Context Management**: OpenTelemetry provides reliable [context propagation](https://opentelemetry.io/docs/concepts/context-propagation/), ensuring that traces are correctly linked even in complex, asynchronous applications.
* **Ecosystem & Interoperability**: You can leverage a vast ecosystem of third-party instrumentations. If a library you use supports OpenTelemetry, its traces can be sent to ABV automatically.

# Learn more

[Setup](/developer/sdks/js-ts/setup)

[Instrumentation](/developer/sdks/js-ts/instrumentation)

[Advanced usage](/developer/sdks/js-ts/advanced-configuration)

[Troubleshooting & FAQ](/developer/sdks/js-ts/troubleshooting-faq)

## Key Features Supported

The JS/TS SDK provides full support for all ABV features:

* [Observability & Tracing](/developer/basic-features/observability-tracing): Comprehensive tracing of LLM applications
* [Sessions](/developer/basic-features/sessions): Group related traces by user journey
* [User Tracking](/developer/basic-features/user-tracking): Associate traces with specific users
* [Metadata](/developer/basic-features/metadata): Add structured context to traces
* [Tags](/developer/basic-features/tags): Label and categorize traces
* [Model Usage & Cost Tracking](/developer/basic-features/model-usage-cost-tracking): Monitor tokens and costs
* [Masking Sensitive Data](/developer/basic-features/masking-sensitive-data): Redact PII and secrets
* [Sampling](/developer/basic-features/sampling): Control trace volume
* [Prompt Management](/developer/prompt-management/get-started): Fetch and link prompts to traces
* [Evaluations](/developer/evaluations/overview): Create datasets and custom scores
* [Guardrails](/developer/guardrails/overview): Implement LLM security guardrails