Python SDK for Vaquero observability and tracing platform
Project description
🚀 Vaquero Python SDK
Comprehensive observability and tracing for AI agents and applications
Zero-config tracing • Auto-instrumentation • Production-ready
⚡ Quick Start
1. Install
pip install vaquero-sdk
2. Configure
import vaquerovaquero.init(api_key="your-api-key")
3. Trace
@vaquero.trace("my_agent")
def process_data(data):
return {"result": data}
Done! ✨
🎯 Key Features
Automatic Tracing
One decorator instruments your entire function with comprehensive observability
LLM Auto-Instrumentation
Automatically captures OpenAI, Anthropic, and other LLM calls with zero code changes
Async-First
Full support for async/await patterns with intelligent batching
Performance Monitoring
Built-in profiling, memory tracking, and performance insights
Production Ready
Circuit breakers, retry logic, and enterprise-grade reliability
Zero Configuration
Environment variables and sensible defaults get you started instantly
📚 Documentation
🔧 Installation Options
💻 Code Examples
Basic Function Tracing
import vaquero
# Configure once
vaquero.init(api_key="your-key")
@vaquero.trace("data_processor")
def process_data(data):
"""Process some data."""
result = {"processed": len(data), "items": data}
return result
# Your function is now automatically traced!
result = process_data(["item1", "item2", "item3"])
Async Support
@vaquero.trace("api_client")
async def fetch_data(url):
"""Async data fetching."""
async with httpx.AsyncClient() as client:
response = await client.get(url)
return response.json()
# Works seamlessly with async/await
result = await fetch_data("https://api.example.com/data")
Manual Span Creation
async with vaquero.span("complex_operation") as span:
span.set_attribute("operation_type", "batch_processing")
span.set_attribute("batch_size", len(data))
# Your complex logic here
result = await process_batch(data)
span.set_attribute("result_count", len(result))
Auto-Instrumentation (Zero Code Changes!)
# Enable LLM auto-instrumentation
vaquero.init(api_key="your-key", auto_instrument_llm=True)
# Now any LLM calls are automatically traced!
import openai
client = openai.OpenAI(api_key="your-key")
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Hello!"}]
)
# System prompts, tokens, timing all captured automatically! ✨
🎨 Advanced Usage
Manual Span Creation
Sync & Async Support
# Same API works for both sync and async!
with vaquero.span("custom_operation") as span:
span.set_attribute("user_id", "12345")
result = expensive_computation()
span.set_attribute("result_size", len(result))
async with vaquero.span("async_operation") as span:
span.set_attribute("operation_type", "ml_inference")
result = await ml_model.predict(data)
span.set_attribute("confidence", result.confidence)
Nested Tracing
Parent-Child Relationships
@vaquero.trace("main_processor")
def main_process(data):
# Parent span automatically created
preprocessed = preprocess_data(data)
# Child span with context
with vaquero.span("validation") as span:
span.set_attribute("data_size", len(preprocessed))
validate_data(preprocessed)
return postprocess_data(preprocessed)</pre>
Custom Configuration
Advanced Setup
from vaquero import SDKConfigconfig = SDKConfig( api_key="your-api-key", project_id="your-project-id", # Optional - auto-provisioned batch_size=100, # Optimize for your workload flush_interval=5.0, # Balance latency vs efficiency max_retries=3, # Handle transient failures capture_inputs=True, # Privacy vs debugging tags={"team": "ml", "env": "prod"} # Global metadata )
vaquero.init(config=config)
Environment Variables
Configuration via Environment
VAQUERO_API_KEY=your-key
VAQUERO_PROJECT_ID=your-project
VAQUERO_ENDPOINT=https://api.vaquero.com
VAQUERO_BATCH_SIZE=50
VAQUERO_AUTO_INSTRUMENT_LLM=true
import vaquero vaquero.init() # Loads from env vars
Error Handling & Resilience
Automatic Error Capture
@vaquero.trace("risky_operation")
def risky_operation(data):
if not data:
raise ValueError("Data cannot be empty")
return process(data)
try:
result = risky_operation([])
except ValueError as e:
# Error automatically captured with full context
print(f"Operation failed: {e}")
# Stack trace, function args, timing all preserved
Performance Monitoring
Built-in Observability
# Check SDK health
stats = vaquero.get_default_sdk().get_stats()
print(f"Traces: {stats['traces_sent']}")
print(f"Memory: {stats['memory_usage_mb']} MB")
Manual control
vaquero.flush() # Force send pending traces
Get current context
from vaquero import get_current_span
span = get_current_span()
span.set_attribute("custom_metric", value)
🔧 Configuration Reference
| Parameter | Type | Default | Description |
|---|---|---|---|
api_key |
string | Required | Your Vaquero API key |
project_id |
string | Optional | Your project identifier (auto-provisioned) |
batch_size |
int | 100 | Traces per batch |
flush_interval |
float | 5.0 | Seconds between flushes |
auto_instrument_llm |
bool | true | Auto-capture LLM calls |
capture_system_prompts |
bool | true | Capture LLM system prompts |
capture_code |
bool | true | Capture source code for analysis |
mode |
string | "development" | Operating mode ("development" or "production") |
🚨 Best Practices
✅ Do
- Use descriptive agent names -
@vaquero.trace("user_authentication_validator") - Add meaningful attributes -
span.set_attribute("user_id", user_id) - Handle errors gracefully - SDK captures exceptions automatically
- Use async context managers -
async with vaquero.span("operation"):
❌ Avoid
- Generic names -
@vaquero.trace("validator")(too vague) - Sensitive data - Don't log passwords, keys, or PII
- Blocking operations - Use async patterns for I/O
- Manual timing - SDK handles timing automatically
🛠️ Development
🏗️ Setup
git clone https://github.com/vaquero/vaquero-python.git cd vaquero-python pip install -e ".[dev]"
🧪 Testing
make test # Run all tests make test-cov # With coverage make lint # Code quality
📝 Contributing
Join our community! See Contributing Guide
📖 Resources
🚀
📚
💡
Getting Started
Complete installation and setup guide
API Reference
Detailed API documentation
Examples
Real-world usage patterns
Need help? Join our Discord community or email support@vaquero.app
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
vaquero_sdk-0.1.0.tar.gz
(80.6 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file vaquero_sdk-0.1.0.tar.gz.
File metadata
- Download URL: vaquero_sdk-0.1.0.tar.gz
- Upload date:
- Size: 80.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4d6c5f9ca1908d5d62b58762ba5c627ab3bb74d447a9d6984bc86d43fb3777df
|
|
| MD5 |
7648fc6e324aa3c9165ac28182fe2e15
|
|
| BLAKE2b-256 |
578cb4e77a5696cdf8bfe7aab3ef57358c733d45bc4ff8e1d4d4a76b3a3d0aec
|
File details
Details for the file vaquero_sdk-0.1.0-py3-none-any.whl.
File metadata
- Download URL: vaquero_sdk-0.1.0-py3-none-any.whl
- Upload date:
- Size: 82.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
753109711c8b705519a54eee3babe7d875decec06f60a747f2995bd6120c4800
|
|
| MD5 |
94cd8266ec18a1f5b2fc5c3c4d6e8e51
|
|
| BLAKE2b-256 |
ada4a8d625a4dba3a608f9f7fb69810cbc9bf8feb21c4f167d40d80d034ac2b3
|
