traces

Query OpenSearch trace data with PPL to analyze agent invocations and errors.

34|32|Updated Jan 28, 2026
One-click install
npx skills add https://github.com/opensearch-project/observability-stack --skill traces
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: traces
Source: https://github.com/opensearch-project/observability-stack/tree/main/claude-code-observability-plugin/skills/traces
Command: npx skills add https://github.com/opensearch-project/observability-stack --skill traces

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Efficiently analyze distributed traces stored in OpenSearch using PPL to uncover agent invocations, tool executions, latency, and errors across OTEL spans.

Core Features & Use Cases

  • PPL-powered tracing to search and summarize agent invocation spans, tool execution spans, and error spans across otel-v1-apm-span-*
  • Performance and reliability insights by identifying slow traces, token usage patterns, and cross-service dependencies via service-map data
  • Use Case: When debugging a GenAI workflow, quickly surface traces for agent calls and tool usage to pinpoint latency and failures.

Quick Start

Ask me to surface the top slow agent invocations or analyze a traceId across spans.

Frequently Asked Questions about traces

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I query OpenSearch traces to investigate GenAI agent invocations and tool executions?

Query OpenSearch traces using PPL to investigate GenAI agent invocations and tool executions by targeting OTEL spans in the otel-v1-apm-span-* indices via the OpenSearch PPL API. This surfaces latency, errors, and token usage for end-to-end trace debugging.

What is the best way to analyze slow traces and token usage patterns in OpenSearch?

Analyzing slow traces and token usage patterns in OpenSearch is best done using PPL queries against otel-v1-apm-span-* and service-map data in otel-v2-apm-service-map-*. This identifies slow agent calls, tool execution failures, and cross-service dependencies.

Can I use PPL to debug errors and latency across OTEL spans stored in OpenSearch?

Yes, you can use PPL to debug errors and latency across OTEL spans stored in OpenSearch. The Skill queries otel-v1-apm-span-* indices to summarize error spans and identify slow traces, providing performance and reliability insights for distributed workflows.

Do I need environment variables to query OpenSearch trace data with PPL?

Yes, you need environment variables to query OpenSearch trace data with PPL. The standard curl-based workflow against the /_plugins/_ppl API endpoint requires basic auth using the OPENSEARCH_ENDPOINT, OPENSEARCH_USER, and OPENSEARCH_PASSWORD environment variables.

How does querying service-map data help with OpenSearch trace debugging?

Querying service-map data in otel-v2-apm-service-map-* helps OpenSearch trace debugging by revealing cross-service dependencies and performance bottlenecks. It complements span data to provide a complete view of distributed workflow reliability and latency.

Why are my GenAI workflow traces failing and how do I pinpoint the failures?

GenAI workflow traces fail due to tool execution errors or latency spikes across distributed services. Pinpoint these failures by querying OpenSearch trace data with PPL to surface agent invocation spans, tool execution errors, and slow traces across OTEL indices.