Untrace Logo

Getting started with Untrace is simple and takes just a few minutes. In this guide, we'll walk you through the three main integration methods and show you how to configure your first routing rules.

Integration Methods

Untrace offers three flexible integration approaches to fit your existing infrastructure:

1. OpenAI-Compatible Proxy (Easiest)

The fastest way to get started is using our OpenAI-compatible proxy. Simply change your base URL:

import openai
 
# Before
client = openai.OpenAI(api_key="your-key")
 
# After
client = openai.OpenAI(
    api_key="your-key",
    base_url="https://api.untrace.dev/v1"
)

That's it! Your existing code will now route through Untrace automatically.

2. Native SDK Integration

For more control, use our native SDKs:

from untrace import UntraceClient
 
client = UntraceClient(
    api_key="your-untrace-key",
    destinations=["langsmith", "langfuse"]
)
 
# Your existing OpenAI calls work unchanged
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

3. Webhook API

For custom integrations, use our webhook API:

import requests
 
payload = {
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}],
    "metadata": {
        "user_id": "123",
        "session_id": "abc"
    }
}
 
response = requests.post(
    "https://api.untrace.dev/v1/webhook",
    json=payload,
    headers={"Authorization": "Bearer your-key"}
)

Setting Up Routing Rules

Once integrated, configure how traces are routed:

Basic Routing

Route all traces to a single destination:

rules:
  - destination: "langsmith"
    condition: "always"

Model-Based Routing

Send different models to different platforms:

rules:
  - destination: "langsmith"
    condition: "model == 'gpt-4'"
  - destination: "langfuse"
    condition: "model == 'claude-3'"

Cost-Based Sampling

Sample expensive models more aggressively:

rules:
  - destination: "langsmith"
    condition: "model == 'gpt-4'"
    sampling: 0.1  # 10% sampling
  - destination: "langfuse"
    condition: "model == 'gpt-3.5-turbo'"
    sampling: 1.0  # 100% sampling

Error-Based Routing

Route errors to monitoring platforms:

rules:
  - destination: "datadog"
    condition: "error == true"
  - destination: "langsmith"
    condition: "error == false"

Advanced Features

PII Detection and Redaction

Untrace automatically detects and redacts PII:

client = UntraceClient(
    api_key="your-key",
    pii_detection=True,
    pii_redaction=True
)

Custom Transformations

Transform data before routing:

def transform_trace(trace):
    # Remove sensitive fields
    if "api_key" in trace:
        del trace["api_key"]
 
    # Add custom metadata
    trace["environment"] = "production"
    return trace
 
client = UntraceClient(
    api_key="your-key",
    transform=transform_trace
)

Cost Monitoring

Track costs across platforms:

# Get cost breakdown
costs = client.analytics.get_costs(
    start_date="2024-01-01",
    end_date="2024-01-31"
)
 
print(f"Total cost: ${costs.total}")
print(f"By platform: {costs.by_platform}")

Best Practices

1. Start Simple

Begin with basic routing and gradually add complexity:

# Start here
rules:
  - destination: "langsmith"
    condition: "always"
 
# Then add sampling
rules:
  - destination: "langsmith"
    condition: "always"
    sampling: 0.5
 
# Finally add conditional routing
rules:
  - destination: "langsmith"
    condition: "model == 'gpt-4'"
  - destination: "langfuse"
    condition: "model == 'gpt-3.5-turbo'"

2. Monitor Performance

Use our dashboard to monitor:

Trace delivery rates
Platform health
Cost trends
Error rates

3. Test in Development

Always test routing rules in development first:

client = UntraceClient(
    api_key="your-key",
    environment="development"  # Routes to test destinations
)

Troubleshooting

Common Issues

Traces not appearing: Check your API key and destination configuration.

High latency: Ensure you're using the closest region endpoint.

Missing metadata: Verify your integration is sending the required fields.

Getting Help

Next Steps

Now that you're set up, explore these advanced features:

Custom Destinations: Add your own webhook endpoints
Advanced Sampling: Implement cost-based and error-biased sampling
Data Governance: Set up PII detection and compliance rules
Analytics: Use our analytics API for custom reporting

Ready to simplify your observability stack? Start your free trial today and route up to 100,000 traces per month at no cost.

Getting Started with Untrace