Core Concepts

Traces and spans

A trace represents a single end-to-end operation (for example, an API request or an agent workflow). Each trace is composed of spans — individual units of work with a start time, duration, and metadata. Spans form a tree structure with parent-child relationships.

OpenTelemetry (OTel)

OpenTelemetry is an open standard for collecting traces, logs, and metrics. The Observability Stack uses OTel protocols (OTLP) for all data ingestion and follows OTel semantic conventions for attribute naming.

GenAI semantic conventions

For AI agent observability, spans use the gen_ai.* attribute namespace defined by the OpenTelemetry GenAI semantic conventions. These include attributes like gen_ai.operation.name, gen_ai.request.model, and gen_ai.usage.input_tokens.

Service maps

Service maps are auto-generated by Data Prepper from trace data. They visualize the dependencies and communication patterns between your services, showing request rates, error rates, and latency.

RED metrics

Rate, Errors, and Duration — the three golden signals computed automatically by Data Prepper from ingested trace spans. These power the APM views in OpenSearch Dashboards.

PPL (Piped Processing Language)

PPL is OpenSearch’s query language for searching and analyzing trace and log data. It uses a pipe syntax similar to Unix commands:

source = otel-v1-apm-span-* | where status.code = 2 | sort - startTime

PromQL

PromQL is Prometheus’s query language for time-series metrics. The Observability Stack supports PromQL natively through the Prometheus data source in OpenSearch Dashboards.

Index patterns

OpenSearch stores observability data in indices following naming conventions:

• otel-v1-apm-span-* — trace spans
• otel-v2-apm-service-map — service map data
• ss4o_logs-* — log data