Data Model - Atla

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

{
  "id": "string", // Unique trace identifier
  "environment": "string", // Deployment environment (PROD | DEV)

  // 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
}

Spans

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

Span Structure

{
  "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
}

Span Annotations

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

Annotation Structure

{
  "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
}

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

{
  "id": "string", // Unique metric ID
  "name": "string", // Metric name (unique per org)

  // Metric configuration
  "dataType": "string" // Value format (BOOLEAN | LIKERT_1_TO_5)
}

Custom Metric Values

{
  "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
}

​Overview

​Traces

​Trace Structure

​Spans

​Span Structure

​Span Annotations

​Annotation Structure

​Custom Metrics

​Custom Metric Definition

​Custom Metric Values