> ## 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.

# Quickstart (JS/TS SDK)

> Get started with ABV tracing in your JavaScript/TypeScript application in under 5 minutes

<Tip>
  If you're creating a new ABV account, the onboarding flow will guide you through these steps automatically. This guide is for manual setup or reference.
</Tip>

<Steps>
  <Step title="Get your API key" icon="key">
    Create an ABV account and generate API credentials:

    1. [Sign up for ABV](https://app.abv.dev/auth/sign-up) (free trial available)
    2. Navigate to **Project Settings** → **API Keys**
    3. Click **Create API Key** and copy your key (starts with `sk-abv-...`)
  </Step>

  <Step title="Install the ABV SDK" icon="download">
    Install the required packages for ABV tracing:

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

    This installs:

    * `@abvdev/tracing` - ABV's tracing SDK
    * `@abvdev/otel` - ABV's OpenTelemetry integration
    * `@opentelemetry/sdk-node` - OpenTelemetry Node.js SDK
    * `dotenv` - Environment variable management
  </Step>

  <Step title="Configure environment variables" icon="gear">
    Create a `.env` file in your project root with your ABV credentials:

    ```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 (uncomment if needed)
    ```

    <Warning>
      Make sure `.env` is in your `.gitignore` to avoid committing secrets.
    </Warning>
  </Step>

  <Step title="Choose your instrumentation method" icon="route">
    ABV offers two ways to instrument your JavaScript/TypeScript application. Choose based on your use case:
  </Step>
</Steps>

# Choose Your Instrumentation Method

<Tabs>
  <Tab title="Gateway Auto-Tracing" icon="route">
    **Best for**: LLM applications that need automatic tracing with zero manual instrumentation

    The ABV Gateway is the fastest way to get complete observability for LLM calls. It automatically captures all metrics without any manual tracing code.

    <Tip>
      New users get \$1 in free credits to test the gateway.
    </Tip>

    **Install the ABV client:**

    ```bash theme={null}
    npm install @abvdev/client dotenv
    ```

    **Create a traced LLM application:**

    ```typescript title="server.ts" theme={null}
    import { ABVClient } from '@abvdev/client';
    import dotenv from 'dotenv';

    // Load environment variables
    dotenv.config();

    // Initialize the ABV client
    const abv = new ABVClient(); // Uses ABV_API_KEY from environment

    async function main() {
      // Make a gateway request - automatically creates a complete trace
      const response = await abv.gateway.chat.completions.create({
        provider: 'openai',
        model: 'gpt-4o-mini',
        messages: [
          { role: 'user', content: 'What is the capital of France?' }
        ]
      });

      // Access the response
      const output = response.choices[0].message.content;
      console.log(`Response: ${output}`);
    }

    main();
    ```

    **What gets captured automatically:**

    * Full conversation context (user query and LLM response)
    * Model and provider information
    * Token usage (input/output counts)
    * Cost tracking (deducted from gateway credits)
    * Latency metrics (total duration and API timing)
    * Complete observability with zero manual instrumentation

    **Switch providers easily:**

    ```typescript theme={null}
    // Try Anthropic's Claude
    const response = await abv.gateway.chat.completions.create({
      provider: 'anthropic',
      model: 'claude-sonnet-4-5',
      messages: [{ role: 'user', content: 'What is the capital of France?' }]
    });

    // Or try Google's Gemini
    const response = await abv.gateway.chat.completions.create({
      provider: 'gemini',
      model: 'gemini-2.0-flash-exp',
      messages: [{ role: 'user', content: 'What is the capital of France?' }]
    });
    ```

    <Info>
      The gateway requires no OpenTelemetry setup. Just install `@abvdev/client` and start making requests.
    </Info>
  </Tab>

  <Tab title="Manual Instrumentation" icon="code">
    **Best for**: Custom workflows where you need fine-grained control over tracing

    Manual instrumentation gives you full control over what gets traced and when. This approach uses OpenTelemetry for flexible, detailed observability.

    **Initialize OpenTelemetry:**

    Create an `instrumentation.ts` file:

    ```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",  // Send traces immediately for development
          flushAt: 1,
          flushInterval: 1,
          additionalHeaders: {
            "Content-Type": "application/json",
            "Accept": "application/json"
          }
        })
      ],
    });

    sdk.start();
    ```

    <Tip>
      The `exportMode: "immediate"` setting ensures traces appear in the ABV dashboard instantly during development. For production, remove this parameter to use batched exports for better performance.
    </Tip>

    **Create your first trace:**

    ```typescript title="server.ts" theme={null}
    import "./instrumentation"; // IMPORTANT: Must be the first import
    import { startActiveObservation, startObservation } from "@abvdev/tracing";

    async function main() {
      await startActiveObservation("user-request", async (span) => {
        span.update({
          input: { query: "What is the capital of France?" },
        });

        // Create a nested LLM generation observation
        const generation = startObservation(
          "llm-call",
          {
            model: "gpt-4o",
            input: [{ role: "user", content: "What is the capital of France?" }],
          },
          { asType: "generation" },
        );

        // Simulate LLM response
        generation
          .update({
            output: { content: "The capital of France is Paris." },
          })
          .end();

        span.update({ output: "Successfully answered." });
      });
    }

    main();
    ```

    <Note>
      This creates a parent `user-request` observation with a nested `llm-call` generation. The nested structure helps you understand multi-step workflows in the ABV dashboard.
    </Note>
  </Tab>
</Tabs>

## Run Your First Trace

Execute your application to send your first trace to ABV:

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

Navigate to [app.abv.dev](https://app.abv.dev) and click **Traces** in the sidebar. You should see your trace with:

* The input query and output
* Model and provider information (if using gateway)
* Nested observation hierarchy
* Timing information and metrics

<Tip>
  If you don't see traces immediately, wait a few seconds and refresh. Check that your API key is correct.
</Tip>

# Next Steps

## Enhance Your Traces

<CardGroup cols={2}>
  <Card title="Add metadata and tags" icon="tags" href="/developer/basic-features/metadata">
    Attach business context to traces for filtering and analysis
  </Card>

  <Card title="Track users and sessions" icon="users" href="/developer/basic-features/sessions">
    Group related traces by user journey or conversation
  </Card>

  <Card title="Monitor costs" icon="dollar-sign" href="/developer/basic-features/cost-tracking-implementation">
    Track LLM spending by user, feature, or model
  </Card>

  <Card title="Store and version datasets" icon="database" href="/developer/evaluations/datasets">
    Manage test datasets and examples for evaluations
  </Card>
</CardGroup>

## Build Production-Grade AI

<CardGroup cols={2}>
  <Card title="Set up guardrails" icon="shield" href="/developer/guardrails/overview">
    Add safety checks, PII detection, and content moderation
  </Card>

  <Card title="Run evaluations" icon="chart-line" href="/developer/evaluations/overview">
    Measure quality with automated LLM-as-judge evaluations
  </Card>

  <Card title="Manage prompts" icon="file-lines" href="/developer/prompt-management/overview">
    Version and deploy prompts without code changes
  </Card>

  <Card title="Access via API" icon="code" href="/developer/platform/api-data-platform/overview">
    Query traces, datasets, and metrics programmatically
  </Card>
</CardGroup>

## Advanced Platform Features

<CardGroup cols={2}>
  <Card title="Analyze metrics" icon="chart-bar" href="/developer/platform/metrics/overview">
    Track performance trends and usage patterns
  </Card>

  <Card title="Explore the SDK" icon="book" href="/developer/sdks/js-ts/overview">
    Learn advanced SDK features and configuration options
  </Card>

  <Card title="Use the LLM Gateway" icon="route" href="/developer/llm-gateway/overview">
    Switch between LLM providers with automatic tracing
  </Card>

  <Card title="Manage team access" icon="users-gear" href="/developer/platform/administration/role-based-access-controls">
    Configure role-based access controls for your team
  </Card>
</CardGroup>