Agent Telemetry Analyzer

This skill exports agent telemetry traces from watsonx Orchestrate and analyzes them directly from raw OTel JSON or Langfuse-format trace JSON to produce structured bug reports with root-cause analysis and fix recommendations.

Two trace formats are supported:

• OTel JSON — produced by the classic TracesController.export_trace_to_json() ADK path and local IBM telemetry servers. Top-level key: traceData.resourceSpans.
• Langfuse JSON — produced by the agentops-v3 REST API (GET /v1/agentops-v3/traces/<id>) and the export_traces_agentops_v3.py script. Top-level key: observations (array of GENERATION / CHAIN / SPAN objects).

Always detect the format first before reading any span data. See the detect_format() helper in Step 3C and the normalization table in Step 4.

Setup: See README.md for prerequisites (ADK installation, .env configuration, and environment activation) before running any scripts.

What this skill does

1. Identifies the trace source — remote hosted env (wxO Traces API or agentops-v3 REST API), local env with IBM telemetry, or JSON files already on disk (OTel or Langfuse format)
2. Exports trace files — discovers traces by agent name or ID, paginates through results, and downloads them as OTel JSON (via ADK TracesController) or Langfuse JSON (via export_traces_agentops_v3.py / search_traces_agentops_v3.py)
3. Analyzes for bugs — detects the JSON format, normalizes spans to a common structure, and scans for hard errors, LLM failures, tool call failures, agent logic bugs, flow issues, token anomalies, and cache efficiency
4. Produces a bug report — structured HTML report with an executive summary, trace summary table, critical issues, warnings, observations, and fix recommendations (multi-trace analysis only — a single-trace request goes straight to the conversational flow report)
5. Produces conversational flow reports — thread-scoped reports that reconstruct multi-turn conversations and surface per-turn failures