> ## 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 (Python SDK)
> Get started with ABV tracing in your Python application in under 5 minutes
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.
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-...`)
Install the required packages for ABV tracing:
```bash theme={null}
pip install abvdev python-dotenv
```
This installs:
* `abvdev` - ABV's Python SDK for tracing and observability
* `python-dotenv` - Environment variable management from `.env` files
Create a `.env` file in your project root with your ABV credentials:
```bash title=".env" theme={null}
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:
**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.
New users get \$1 in free credits to test the gateway.
```python theme={null}
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:**
```python theme={null}
# 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 instrumentation
The `@observe` decorator is the easiest way to add tracing. It automatically captures function name, arguments, return value, and timing.
```python theme={null}
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 when
Context managers give you more control over instrumentation. They're ideal for complex workflows where you need to track specific operations.
```python theme={null}
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:
```bash theme={null}
python your_script.py
```
Navigate to [app.abv.dev](https://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
Attach business context to traces for filtering and analysis
Group related traces by user journey or conversation
Track LLM spending by user, feature, or model
Manage test datasets and examples for evaluations
## Build Production-Grade AI
Add safety checks, PII detection, and content moderation
Measure quality with automated LLM-as-judge evaluations
Version and deploy prompts without code changes
Query traces, datasets, and metrics programmatically
## Advanced Platform Features
Track performance trends and usage patterns
Learn advanced SDK features and configuration options
Switch between LLM providers with automatic tracing
Configure role-based access controls for your team