Agent tracing

You can use Respan Traces to trace your LLM requests and responses.

What is traces?

Traces are a chained collection of workflows and tasks. You can use tree views and waterfalls to better track dependencies and latency.

Use agent tracing

1. Get your Respan API key

After you create an account on Respan, you can get your API key from the API keys page.

2. Respan Native (OpenTelemetry)

You just need to add the respan_tracing package to your project and annotate your workflows.

Python

1. Install the SDK

   Python Requirement: This package requires Python 3.9 or later.

   pip

   pip install respan-tracing
   
2. Set up Environment Variables

   Get your API key from the API Keys page in Settings, then configure it in your environment:

   .env

   RESPAN_BASE_URL="https://api.respan.ai/api"
   RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
   
3. A full example with LLM calls

   Use the @workflow and @task decorators to instrument your code:

   Python

   import os
   from openai import OpenAI
   from respan_tracing.decorators import workflow, task
   from respan_tracing.main import RespanTelemetry
   
   # Initialize Respan Telemetry
   os.environ["RESPAN_API_KEY"] = "YOUR_RESPAN_API_KEY"
   k_tl = RespanTelemetry()
   
   # Initialize OpenAI client
   client = OpenAI()
   
   @task(name="joke_creation")
   def create_joke():
       completion = client.chat.completions.create(
           model="gpt-4o-mini",
           messages=[{"role": "user", "content": "Tell me a joke about AI"}],
           temperature=0.7,
           max_tokens=100,
       )
       return completion.choices[0].message.content
   
   @workflow(name="simple_joke_workflow")
   def joke_workflow():
       joke = create_joke()
       return joke
   
   if __name__ == "__main__":
       result = joke_workflow()
       print(result)
   

JS/TS

1. Install the SDK

   Install the package using your preferred package manager:

   npm install @respan/tracing
   # or yarn
   
   yarn add @respan/tracing
   
2. Set up Environment Variables

   Get your API key from the API Keys page in Settings, then configure it in your environment:

   .env

   RESPAN_BASE_URL="https://api.respan.ai/api"
   RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
   OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
   
3. Create a simple workflow

   server.ts

   import { RespanTelemetry } from '@respan/tracing';
   import OpenAI from 'openai';
   
   // Initialize Respan Telemetry
   const respanAi = new RespanTelemetry({
       apiKey: process.env.RESPAN_API_KEY || "",
       appName: 'test-app',
       disableBatch: true  // For testing, disable batching
   });
   
   // Initialize OpenAI client
   const openai = new OpenAI();
   
   async function createJoke() {
       return await respanAi.withTask(
           { name: 'joke_creation' },
           async () => {
               const completion = await openai.chat.completions.create({
                   messages: [{ role: 'user', content: 'Tell me a joke about AI' }],
                   model: 'gpt-4o-mini',
                   temperature: 0.7,
                   max_tokens: 100
               });
               return completion.choices[0].message.content;
           }
       );
   }
   
   async function simpleJokeWorkflow() {
       return await respanAi.withWorkflow(
           { name: 'simple_joke_workflow' },
           async () => {
               const joke = await createJoke();
               return joke;
           }
       );
   }
   
   // Run the workflow
   async function main() {
       const result = await simpleJokeWorkflow();
       console.log(result);
   }
   
   main().catch(console.error);
   

Optional HTTP instrumentation If you see logs like:

install the OpenTelemetry instrumentations to enable and silence these messages:

pip install opentelemetry-instrumentation-requests opentelemetry-instrumentation-urllib3

This is optional; tracing works without them. Add only if your app uses requests or urllib3.

3. View your traces

You can now see your traces in the Traces.

Integrate with your existing AI framework

Respan also integrates seamlessly with popular AI frameworks to give you complete observability into your agent workflows.