> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atla-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry GenAI Events

> How to interpret and work with the GenAI event data available through Atla Insights.

## Overview

Atla Insights captures generative AI interactions using the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/), 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.

```jsonc icon="code" lines theme={null}
{
  "event_name": "gen_ai.system.message",
  "body": {
    "content": "string",
    "name?": "string"  // Optional system message identifier
  }
}
```

#### `gen_ai.user.message`

User inputs to the AI system.

```jsonc icon="code" lines theme={null}
{
  "event_name": "gen_ai.user.message",
  "body": {
    "content": "string | null",  // null for multimodal requests
    "name?": "string"  // Optional user identifier
  }
}
```

#### `gen_ai.assistant.message`

AI responses, including tool/function calls.

```jsonc icon="code" lines theme={null}
{
  "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
  }
}
```

#### `gen_ai.tool.message`

Results from tool/function executions.

```jsonc icon="code" lines theme={null}
{
  "event_name": "gen_ai.tool.message",
  "body": {
    "content": "string",  // Tool execution result
    "id": "string | null"  // Tool call identifier
  }
}
```

### Choice Events

#### `gen_ai.choice`

Captures AI response selection and metadata.

```jsonc icon="code" lines theme={null}
{
  "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)
  }
}
```

### 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**:

```jsonc icon="code" lines theme={null}
[
  { "role": "system", "content": "..." },
  { "role": "user", "content": "..." },
  { "role": "assistant", "content": "...", "tool_calls": ["..."] }
]
```

**Becomes OpenTelemetry Events**:

```jsonc icon="code" lines theme={null}
[
  { "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