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.

Get your API key

Create an ABV account and generate API credentials:

Sign up for ABV (free trial available)
Navigate to Project Settings → API Keys
Click Create API Key and copy your key (starts with sk-abv-...)

Install the ABV SDK

Install the required packages for ABV tracing:

pip install abvdev python-dotenv

This installs:

abvdev - ABV’s Python SDK for tracing and observability
python-dotenv - Environment variable management from .env files

Configure environment variables

Create a .env file in your project root with your ABV credentials:

.env

ABV_API_KEY="sk-abv-..."
ABV_HOST="https://app.abv.dev"  # US region
# ABV_HOST="https://eu.app.abv.dev"  # EU region (uncomment if needed)

Make sure .env is in your .gitignore to avoid committing secrets.

Choose Your Instrumentation Method

ABV’s Python SDK offers multiple ways to create traces. Choose based on your use case:

Gateway Auto-Tracing
@observe Decorator
Context Managers

Best for: LLM applications that need automatic tracing with zero manual instrumentationThe ABV Gateway is the fastest way to get complete observability for LLM calls. It automatically captures all metrics without any manual tracing code.

New users get $1 in free credits to test the gateway.

from dotenv import load_dotenv
from abvdev import ABV

# Load environment variables
load_dotenv()

# Initialize the ABV client
abv = ABV()  # Uses ABV_API_KEY from environment

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

# Access the response
output = response['choices'][0]['message']['content']
print(f"Response: {output}")

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)

Switch providers easily:

# Try Anthropic's Claude
response = 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
response = abv.gateway.chat.completions.create(
    provider='gemini',
    model='gemini-2.0-flash-exp',
    messages=[{'role': 'user', 'content': 'What is the capital of France?'}]
)

The gateway requires no additional setup beyond installing abvdev. It automatically handles tracing, cost tracking, and provider switching.

Best for: Simple functions where you want automatic instrumentationThe @observe decorator is the easiest way to add tracing. It automatically captures function name, arguments, return value, and timing.

from dotenv import load_dotenv
from abvdev import observe, get_client

# Load environment variables
load_dotenv()

@observe
def my_function():
    # Function logic here
    return "Hello, world!"

# Call the function - it's automatically traced
my_function()

# Flush events in short-lived applications
abv = get_client()
abv.flush()

What gets captured:

Function name and arguments
Return value
Execution time
Any exceptions raised

The @observe decorator is perfect for quick instrumentation. Just add it to any function you want to trace!

Best for: Fine-grained control over what you track and whenContext managers give you more control over instrumentation. They’re ideal for complex workflows where you need to track specific operations.

from dotenv import load_dotenv
from abvdev import get_client

load_dotenv()
abv = get_client()

# Create a parent span for the entire request
with abv.start_as_current_span(name="process-request") as span:
    span.update(input={"query": "What is the capital of France?"})

    # Create a nested generation for an LLM call
    with abv.start_as_current_observation(
        as_type='generation',
        name="llm-call",
        model="gpt-4o"
    ) as generation:
        # Simulate LLM response
        generation.update(output="The capital of France is Paris.")

    span.update(output="Processing complete")

# Flush events in short-lived applications
abv.flush()

Key benefits:

Explicit control over what’s tracked
Easy nesting of observations
Update metadata at any point
Automatic cleanup when context exits

Context managers automatically close spans when exiting the with block, preventing memory leaks and ensuring data is sent to ABV.

Run Your First Trace

Execute your Python script to send your first trace to ABV:

python your_script.py

Navigate to app.abv.dev and click Traces in the sidebar. You should see your trace with:

The function/span name
Input and output data
Nested observation hierarchy (if using context managers or gateway)
Timing information and metrics

If you don’t see traces immediately, wait a few seconds and refresh. Make sure you called abv.flush() for short-lived scripts (not needed for gateway requests).

When to Use `flush()`

The abv.flush() call is only needed for short-lived scripts that exit immediately. Long-running applications (web servers, background workers) don’t need it.

Use flush() for:

CLI scripts
Batch processing jobs
One-off tasks

Don’t use flush() for:

FastAPI/Flask web applications
Django applications
Long-running services

Next Steps

Enhance Your Traces

Add metadata and tags

Attach business context to traces for filtering and analysis

Track users and sessions

Monitor costs

Track LLM spending by user, feature, or model

Store and version datasets

Manage test datasets and examples for evaluations

Build Production-Grade AI

Set up guardrails

Add safety checks, PII detection, and content moderation

Run evaluations

Measure quality with automated LLM-as-judge evaluations

Manage prompts

Version and deploy prompts without code changes

Access via API

Query traces, datasets, and metrics programmatically

Advanced Platform Features

Analyze metrics

Track performance trends and usage patterns

Explore the SDK

Learn advanced SDK features and configuration options

Use the LLM Gateway

Switch between LLM providers with automatic tracing

Manage team access

Configure role-based access controls for your team

Getting Started

Basic Features

LLM Gateway

Guardrails

Evaluations

Prompt Management

Cookbook

SDKs

Platform

Support

Quickstart (Python SDK)

Choose Your Instrumentation Method

Run Your First Trace

When to Use `flush()`

Next Steps

Enhance Your Traces

Add metadata and tags

Track users and sessions

Monitor costs

Store and version datasets

Build Production-Grade AI

Set up guardrails

Run evaluations

Manage prompts

Access via API

Advanced Platform Features

Analyze metrics

Explore the SDK

Use the LLM Gateway

Manage team access

Getting Started

Basic Features

LLM Gateway

Guardrails

Evaluations

Prompt Management

Cookbook

SDKs

Platform

Support

​Choose Your Instrumentation Method

​Run Your First Trace

​When to Use flush()

​Next Steps

​Enhance Your Traces

Add metadata and tags

Track users and sessions

Monitor costs

Store and version datasets

​Build Production-Grade AI

Set up guardrails

Run evaluations

Manage prompts

Access via API

​Advanced Platform Features

Analyze metrics

Explore the SDK

Use the LLM Gateway

Manage team access

Choose Your Instrumentation Method

Run Your First Trace

When to Use `flush()`

Next Steps

Enhance Your Traces

Build Production-Grade AI

Advanced Platform Features