Skip to main content
Sessions provide automatic span linking for multi-turn conversations. Each call in a session is automatically connected to previous calls, making it easy to visualize conversation flows in the Tracia dashboard.

​
Creating a Session

import { Tracia } from 'tracia';

const tracia = new Tracia({ apiKey: process.env.TRACIA_API_KEY });

// Start a new session
const session = tracia.createSession();

// Or continue an existing trace (e.g., across HTTP requests)
const session = tracia.createSession({
  traceId: 'tr_existing_trace_id',
  parentSpanId: 'sp_last_span_id',  // optional: chain from a specific span
});
OptionTypeDescription
traceIdstringContinue an existing trace instead of creating a new one
parentSpanIdstringChain from a specific span in the existing trace

​
Basic Usage

const session = tracia.createSession();

// First call - creates the session (trace)
const result1 = await session.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'What is the weather?' }],
});
// result1.spanId = "sp_abc123"
// session.getTraceId() = "tr_xyz789" (session ID)

// Second call - automatically linked to first
const result2 = await session.runLocal({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'What is the weather?' },
    result1.message,
    { role: 'user', content: 'What about tomorrow?' },
  ],
});
// Automatically sends: traceId: "tr_xyz789", parentSpanId: "sp_abc123"

// Third call - chain continues
const result3 = await session.runLocal({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'What is the weather?' },
    result1.message,
    { role: 'user', content: 'What about tomorrow?' },
    result2.message,
    { role: 'user', content: 'Thanks!' },
  ],
});
// Automatically sends: traceId: "tr_xyz789", parentSpanId: result2.spanId

​
How It Works

When you use a session:
  1. First call - A trace ID is generated to group all spans in this session
  2. Subsequent calls - Automatically include:
    • traceId: The session’s trace ID (groups all spans together)
    • parentSpanId: The previous span’s ID (creates a chain)
This creates a tree structure in the Tracia dashboard where you can see the full conversation flow.

​
TraciaSession Methods

​
runLocal()

Same as tracia.runLocal() but with automatic span linking: 
const result = await session.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});

​
runResponses()

Same as tracia.runResponses() but with automatic span linking: 
const result = await session.runResponses({
  model: 'o3-mini',
  input: [
    { role: 'developer', content: 'You are helpful.' },
    { role: 'user', content: 'What is 2+2?' },
  ],
});

​
getTraceId()

Returns the session’s trace ID (groups all spans): 
const traceId = session.getTraceId();
// Returns: "tr_abc123" or undefined if no calls made yet

​
getLastSpanId()

Returns the most recent span ID: 
const lastId = session.getLastSpanId();
// Returns: "sp_xyz789" or undefined if no calls made yet

​
reset()

Clears session state to start a new trace: 
session.reset();
// Next call will start a new trace session

​
Continuing Existing Traces

Use createSession with a traceId to continue a trace across requests or services: 
// API handler - continue a trace from a previous request
app.post('/chat', async (req, res) => {
  const { message, traceId, lastSpanId } = req.body;

  const session = tracia.createSession({
    traceId,             // Continue the same trace
    parentSpanId: lastSpanId,  // Chain from the last span
  });

  const result = await session.runLocal({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: message }],
  });

  res.json({
    text: result.text,
    traceId: session.getTraceId(),
    lastSpanId: result.spanId,
  });
});

​
Manual Span Linking

If you prefer manual control, you can use traceId and parentSpanId directly: 
// First call
const result1 = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});

// Second call - manually link
const result2 = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [...],
  traceId: result1.spanId,      // Use first span as session ID
  parentSpanId: result1.spanId, // Parent is the first span
});

// Third call - continue chain
const result3 = await tracia.runLocal({
  model: 'gpt-4o',
  messages: [...],
  traceId: result1.spanId,      // Same session
  parentSpanId: result2.spanId, // Parent is the second span
});

​
Streaming with Sessions

Sessions work with streaming: 
const session = tracia.createSession();

const stream = session.runLocal({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Write a poem.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

const result = await stream.result;
// session.getTraceId() is now set

​
Use Cases

  • Chat applications: Track full conversation threads
  • Multi-step agents: Link planning, execution, and verification steps
  • RAG pipelines: Connect retrieval and generation spans
  • Debugging: Easily find all spans related to a user session