​
Overview

Atla Insights captures generative AI interactions using the OpenTelemetry GenAI Semantic Conventions, an emerging standard for observing AI systems. This guide explains how to interpret and work with the GenAI event data available through our platform.

​
What are OpenTelemetry GenAI Events?

OpenTelemetry GenAI events are structured telemetry data that capture the inputs, outputs, and metadata of generative AI operations. They provide a standardized way to observe AI system behavior across different providers (OpenAI, Anthropic, etc.) while maintaining consistent data structures. Each event represents a discrete piece of an AI interaction:
  • Message events capture individual messages in a conversation
  • Choice events capture the AI’s response options and selections

​
Standard Background

The OpenTelemetry GenAI semantic conventions are actively developed by major AI and observability companies including OpenAI, Google, Microsoft, and Amazon. The standard aims to:
  • Provide consistent telemetry across AI providers
  • Enable privacy-conscious AI observability
  • Support both simple chat and complex agent workflows
  • Allow vendor-specific extensions while maintaining interoperability

​
Event Types and Structure

​
Message Events

Message events follow the pattern gen_ai.{role}.message and capture conversation flow:

​
gen_ai.system.message

System prompts and instructions that set AI behavior. TypeScript: 
{
  event_name: "gen_ai.system.message",
  body: {
    content: "You are a helpful assistant...",
    name?: string  // Optional system message identifier
  }
}
Python: 
{
    "event_name": "gen_ai.system.message",
    "body": {
        "content": "You are a helpful assistant...",
        "name": "system_prompt_v1"  # Optional system message identifier
    }
}

​
gen_ai.user.message

User inputs to the AI system. TypeScript: 
{
  event_name: "gen_ai.user.message",
  body: {
    content: string | null,  // null for multimodal requests
    name?: string           // Optional user identifier
  }
}
Python: 
{
    "event_name": "gen_ai.user.message",
    "body": {
        "content": "What is the weather like?",  # None for multimodal requests
        "name": "user_123"  # Optional user identifier
    }
}

​
gen_ai.assistant.message

AI responses, including tool/function calls. TypeScript: 
{
  event_name: "gen_ai.assistant.message",
  body: {
    content?: string | null,     // Response text
    tool_calls?: ToolCall[],     // Function calls made
    name?: string,               // Assistant identifier
    refusal?: string            // Refusal reason
  }
}
Python: 
{
    "event_name": "gen_ai.assistant.message",
    "body": {
        "content": "I'll check the weather for you.",  # Response text
        "tool_calls": [  # Function calls made
            {
                "id": "call_123",
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "arguments": '{"location": "San Francisco"}'
                }
            }
        ],
        "name": "assistant",  # Assistant identifier
        "refusal": None  # Refusal reason
    }
}

​
gen_ai.tool.message

Results from tool/function executions. TypeScript: 
{
  event_name: "gen_ai.tool.message",
  body: {
    content: string,    // Tool execution result
    id: string | null   // Tool call identifier
  }
}
Python: 
{
    "event_name": "gen_ai.tool.message",
    "body": {
        "content": '{"temperature": 72, "condition": "sunny"}',  # Tool execution result
        "id": "call_123"  # Tool call identifier
    }
}

​
Choice Events

​
gen_ai.choice

Captures AI response selection and metadata. TypeScript: 
{
  event_name: "gen_ai.choice",
  body: {
    index: number,              // Choice index (0-based)
    finish_reason: string | null, // Why generation stopped
    message: {                   // The selected response
      content?: string,
      tool_calls?: ToolCall[],
      annotations?: Annotation[]
    },
    tools?: ChatCompletionToolParam[]  // Available tools (Atla extension)
  }
}
Python: 
{
    "event_name": "gen_ai.choice",
    "body": {
        "index": 0,  # Choice index (0-based)
        "finish_reason": "stop",  # Why generation stopped
        "message": {  # The selected response
            "content": "The weather in San Francisco is 72°F and sunny.",
            "tool_calls": None,
            "annotations": []
        },
        "tools": [  # Available tools (Atla extension)
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get current weather for a location"
                }
            }
        ]
    }
}

​
Common Metadata

All events include:
  • event_timestamp: ISO 8601 timestamp
  • attributes: Contains gen_ai.system (required) and other metadata
  • source: Optional span ID reference

​
Relationship to OpenAI’s Data Model

OpenTelemetry GenAI events map closely to OpenAI’s chat completion structure:

​
OpenAI → OpenTelemetry Mapping

OpenAI Messages Array: 
[
  { role: "system", content: "..." },
  { role: "user", content: "..." },
  { role: "assistant", content: "...", tool_calls: [...] }
]
Becomes OpenTelemetry Events: 
[
  { event_name: "gen_ai.system.message", body: { content: "..." } },
  { event_name: "gen_ai.user.message", body: { content: "..." } },
  { event_name: "gen_ai.assistant.message", body: { content: "...", tool_calls: [...] } }
]
OpenAI Choices → gen_ai.choice events with finish reasons, tool calls, and response metadata.

​
Interpreting Event Data

​
Conversation Flow

Reconstruct conversations by ordering message events by timestamp:
  1. System messages establish context
  2. User/assistant messages alternate in conversation
  3. Tool messages provide function call results
  4. Choice events show response selection process

​
Tool/Function Usage

Track AI function calling through the event sequence:
  1. gen_ai.assistant.message with tool_calls → AI requests function execution
  2. gen_ai.tool.message with matching id → Function execution result
  3. Next gen_ai.assistant.message → AI processes function result