​
Overview

This guide explains the core data model for developers consuming AI observability data through Atla’s SDK and APIs. Our data model is built on OpenTelemetry standards and captures the complete lifecycle of AI applications from traces to custom metrics.

​
Traces

A Trace represents a complete AI interaction or workflow - typically a full conversation or agent execution.

​
Trace Structure

TypeScript: 
interface Trace {
  id: string;                    // Unique trace identifier
  environment: "PROD" | "DEV";   // Deployment environment

  // Execution metadata
  isSuccess: boolean | null;     // Overall success status
  isCompleted: boolean;          // Whether trace finished

  // Timing information
  startedAt: string;             // Trace start time (ISO 8601)
  endedAt: string;               // Trace completion time (ISO 8601)

  // Custom metadata
  metadata: { [key: string]: string } | null; // Custom trace metadata

  // Related data
  spans?: Span[];                // Individual AI operations
  customMetricValues?: CustomMetricValue[]; // Quality metrics
}
Python: 
{
    "id": "trace_abc123",
    "environment": "PROD",

    # Execution metadata
    "isSuccess": True,  # Can also be False or null
    "isCompleted": True,

    # Timing information
    "startedAt": "2024-01-15T10:30:00Z",
    "endedAt": "2024-01-15T10:32:30Z",

    # Custom metadata
    "metadata": {"user_id": "user_123", "session_type": "chat"},  # Can be null

    # Related data
    "spans": [...],  # List of span objects
    "customMetricValues": [...]  # Quality metrics
}

​
Spans

A Span represents an individual operation within a trace - typically a single AI model call, tool execution, or processing step.

​
Span Structure

TypeScript: 
interface Span {
  id: string;                    // Unique span identifier
  traceId: string;               // Parent trace reference

  // Span hierarchy
  parentSpanId: string | null;   // Parent span in call stack

  // Span metadata
  spanName: string | null;       // Operation name (e.g., "openai.chat.completions")

  // Timing
  startTimestamp: string;        // Operation start (ISO 8601)
  endTimestamp: string;          // Operation completion (ISO 8601)

  // OpenTelemetry data
  otelEvents: any[];             // GenAI events (messages, choices)

  // Analysis data
  isException: boolean | null;   // Whether span had errors

  // Related data (when included)
  annotations?: SpanAnnotation[]; // Issue analysis
}
Python: 
{
    "id": "span_def456",
    "traceId": "trace_abc123",

    # Span hierarchy
    "parentSpanId": "span_parent123",  # Can be null

    # Span metadata
    "spanName": "openai.chat.completions",  # Can be null

    # Timing
    "startTimestamp": "2024-01-15T10:30:15Z",
    "endTimestamp": "2024-01-15T10:30:18Z",

    # OpenTelemetry data
    "otelEvents": [
        # GenAI message and choice events (see GenAI Events Guide)
        {"event_name": "gen_ai.user.message", "body": {...}},
        {"event_name": "gen_ai.choice", "body": {...}}
    ],

    # Analysis data
    "isException": False,  # Can be True or null

    # Related data (when requested with include parameter)
    "annotations": [...]  # Issue analysis
}

​
Span Annotations

Span Annotations provide AI-powered analysis of potential issues, failures, or interesting patterns within individual spans.

​
Annotation Structure

TypeScript: 
interface SpanAnnotation {
  id: string;                    // Unique annotation ID
  spanId: string;                // Target span reference

  // Issue classification
  failureMode: string;           // Type of issue detected

  // Atla's AI analysis
  atlaCritique: string;          // AI-generated explanation
}
Python: 
{
    "id": "ann_ghi789",
    "spanId": "span_def456",

    # Issue classification
    "failureMode": "hallucination",

    # Atla's AI analysis
    "atlaCritique": "The model provided factually incorrect information about the weather API endpoint, suggesting a non-existent URL that would cause downstream failures."
}

​
Custom Metrics

Custom Metrics capture quantitative quality measurements across traces, such as user satisfaction scores, factual accuracy ratings, or business-specific KPIs.

​
Custom Metric Definition

TypeScript: 
interface CustomMetric {
  id: string;                    // Unique metric ID
  name: string;                  // Metric name (unique per org)

  // Metric configuration
  dataType: "BOOLEAN" | "LIKERT_1_TO_5"; // Value format
}
Python: 
{
    "id": "metric_jkl012",
    "name": "user_satisfaction",

    # Metric configuration
    "dataType": "LIKERT_1_TO_5"  # 1-5 scale
}

​
Custom Metric Values

TypeScript: 
interface CustomMetricValue {
  id: string;                    // Unique value ID
  customMetricId: string;        // Parent metric reference
  traceId: string;               // Target trace

  // Metric result
  value: string;                 // The measured value ("true", "3", etc.)

  // Related data (when included)
  customMetric?: CustomMetric;   // The metric definition
}
Python: 
{
    "id": "value_mno345",
    "customMetricId": "metric_jkl012",
    "traceId": "trace_abc123",

    # Metric result
    "value": "4",  # 4 out of 5 satisfaction

    # Related data (when included)
    "customMetric": {
        "id": "metric_jkl012",
        "name": "user_satisfaction",
        "dataType": "LIKERT_1_TO_5"
    }
}