Session Tracking

When building chat applications or multi-turn workflows, you often need to group traces from multiple requests into a single session. This guide shows how to track sessions using OpenTelemetry attributes.

Setting session attributes

Add session IDs to spans using the ag.session.id attribute. Agenta recognizes this attribute and groups all spans with the same value together.

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('my-app');

function processChatMessage(message: string, sessionId: string) {
  return tracer.startActiveSpan('process_message', (span) => {
    try {
      // Set session ID attribute
      span.setAttribute('ag.session.id', sessionId);

      // Your processing logic
      const response = generateResponse(message);
      return response;
    } finally {
      span.end();
    }
  });
}

Session ID format

Session IDs can be any string value. Common patterns:

• UUIDs: 550e8400-e29b-41d4-a716-446655440000
• Composite IDs: user_123_session_456
• Custom formats: chat_2024-01-15_abc123