Skip to main content
The modular ABV TypeScript SDK is built on OpenTelemetry for robust observability, better context management, and easy integration with third-party libraries. Official Link: 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: 
npm install @abvdev/tracing @abvdev/otel @opentelemetry/sdk-node
Learn more about the packages here.

​
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.
.env
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.
instrumentation.ts
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. 
npm install dotenv
instrumentation.ts
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).
index.ts
import "./instrumentation"; // Must be the first import
Learn more about setting up OpenTelemetry here.

​
4) Instrument your application

Use one of the native ABV framework integrations 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 page for more details.
index.ts
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. 
npx tsx index.ts

​
Packages

The ABV SDK is designed to be modular. Here’s an overview of the available packages:
PackageDescriptionEnvironment
@abvdev/coreCore utilities, types, and logger shared across packages.Universal JS
@abvdev/clientClient for features like prompts, datasets, and scores.Universal JS
@abvdev/tracingCore OpenTelemetry-based tracing functions (startObservation, etc.).Universal JS
@abvdev/otelThe 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, 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 Instrumentation Advanced usage Troubleshooting & FAQ

​
Key Features Supported

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