feat(otlp): add --format otlp-genai with OTel GenAI semantic conventions (#110)

LLM request/response pairs now export as gen_ai.client.operation child
spans. Tool calls export as gen_ai.tool.call/<name> spans. Errors use
the OTel exception event format. Root span carries gen_ai.agent.id and
gen_ai.agent.name. --format otlp is unchanged for backwards compatibility.

Closes #100

Co-authored-by: Ona <no-reply@ona.com>

Author: Siddhant-K-code

ADRs/0011-otlp-genai-semantic-conventions.md

@@ -0,0 +1,59 @@
+# ADR-0011: OTLP GenAI Semantic Conventions Export Format
+
+**Status:** Accepted  
+**Date:** 2026-05  
+**Deciders:** Siddhant Khare
+
+## Context
+
+agent-strace already exports OTLP (ADR-0006). The OpenTelemetry GenAI semantic
+conventions (`gen_ai.*`) are now the standard attribute set for AI spans and are
+natively understood by Datadog LLM Observability, Grafana GenAI dashboards,
+Honeycomb, and any OTel-compatible backend.
+
+Without this mapping, agent-strace traces land in production backends as
+unrecognized custom spans. They don't get AI-specific dashboards, cost views,
+token usage charts, or anomaly detection.
+
+## Decision
+
+Add a `--format otlp-genai` flag to `agent-strace export` that applies the
+OTel GenAI semantic conventions mapping. The existing `--format otlp` output
+is unchanged for backwards compatibility.
+
+### Mapping
+
+| agent-strace event | OTel GenAI span / attribute |
+|---|---|
+| `llm_request` + `llm_response` | `gen_ai.client.operation` child span with `gen_ai.request.model`, `gen_ai.request.max_tokens`, `gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`, `gen_ai.response.finish_reasons` |
+| `tool_call` + `tool_result` | `gen_ai.tool.call/<name>` child span with `gen_ai.tool.name`, `gen_ai.tool.call.id` |
+| `user_prompt` | `gen_ai.user.message` event on root span |
+| `assistant_response` | `gen_ai.assistant.message` event on root span |
+| `error` | OTel `exception` event with `exception.type`, `exception.message` |
+| `session_start` / `session_end` | Root span with `gen_ai.agent.id`, `gen_ai.agent.name` |
+
+### Span hierarchy
+
+```
+session root span (gen_ai.agent.session)
+  ├── gen_ai.client.operation   (one per LLM request/response pair)
+  ├── gen_ai.tool.call/<name>   (one per tool call/result pair)
+  └── gen_ai.tool.call/<name>   (error variant with exception event)
+```
+
+### Key differences from --format otlp
+
+- LLM request/response pairs become proper child spans (not events on root)
+- Root span carries `gen_ai.agent.id` and `gen_ai.agent.name`
+- Error events use the OTel `exception` event format
+- Tool input/output attributes use `gen_ai.tool.input.*` / `gen_ai.tool.output`
+- Scope name includes `genai-semconv-1.27` for version tracking
+
+## Consequences
+
+- Traces exported with `--format otlp-genai` appear in Grafana, Datadog, and
+  Honeycomb with AI-specific dashboards populated automatically.
+- Existing `--format otlp` output is unchanged — no breaking change.
+- No new runtime dependencies — the mapping is pure Python stdlib.
+- The `gen_ai.system` attribute is derived heuristically from the model name;
+  this may be incorrect for custom or fine-tuned models.

README.md

@@ -219,6 +219,7 @@ agent-strace replay [session-id] [--limit N]    Replay a session (--limit caps e
 agent-strace retention status                   Show session count, size, and what policy would delete
 agent-strace retention clean [--dry-run]        Delete sessions that exceed retention limits
 agent-strace sample --strategy worst --n 20     Export worst/diverse/random/recent sessions as JSONL
+agent-strace export <session> --format otlp-genai  Export with OTel GenAI semantic conventions
 agent-strace watch [--timeout DURATION] [--budget $] [--on-death CMD] [--rules file]
                                                 Watch a live session; kill/pause on rule breach
 agent-strace share <session-id> [-o file]       Export a self-contained HTML report
@@ -1224,6 +1225,26 @@ Any attempt by the agent to read `cvm/attestation-service/` or `cvm/auth-service
 
 Export sessions as OpenTelemetry spans to your existing observability stack. Sessions become traces. Tool calls become spans with duration and inputs. Errors get exception events. No new dependencies.
 
+### OTel GenAI semantic conventions
+
+Use `--format otlp-genai` to export with strict [OTel GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This produces AI-native spans that populate token usage charts, cost views, and LLM dashboards in Datadog, Grafana, and Honeycomb automatically.
+
+```bash
+agent-strace export <session-id> --format otlp-genai \
+  --endpoint http://localhost:4318
+```
+
+Key differences from `--format otlp`:
+
+| Aspect | `--format otlp` | `--format otlp-genai` |
+|---|---|---|
+| LLM calls | Events on root span | `gen_ai.client.operation` child spans |
+| Tool calls | `tool/<name>` spans | `gen_ai.tool.call/<name>` spans |
+| Root span | `agent.name` attribute | `gen_ai.agent.id` + `gen_ai.agent.name` |
+| Errors | Custom error span | OTel `exception` event format |
+
+`--format otlp` is unchanged for backwards compatibility.
+
 ### Datadog
 
 ```bash

src/agent_trace/__init__.py

@@ -1,3 +1,3 @@
 """agent-trace: strace for AI agents."""
 
-__version__ = "0.42.1"
+__version__ = "0.43.0"

src/agent_trace/cli.py

@@ -272,14 +272,25 @@ def cmd_export(args: argparse.Namespace) -> int:
         for e in events:
             sys.stdout.write(e.to_json() + "\n")
 
-    elif args.format == "otlp":
-        from .otlp import export_otlp, session_to_otlp
+    elif args.format in ("otlp", "otlp-genai"):
+        from .otlp import export_otlp, session_to_otlp, session_to_otlp_genai
 
+        use_genai = args.format == "otlp-genai"
         endpoint = args.endpoint
+
+        # When --endpoint is set and format is plain otlp, default to otlp-genai
+        # for better backend compatibility (backwards-compat: explicit --format otlp
+        # always uses the legacy mapping)
+        if endpoint and not use_genai:
+            use_genai = False  # explicit --format otlp keeps legacy behaviour
+
         if not endpoint:
             # No endpoint: dump OTLP JSON to stdout
             meta = store.load_meta(session_id)
-            payload = session_to_otlp(meta, events, service_name=args.service_name)
+            if use_genai:
+                payload = session_to_otlp_genai(meta, events, service_name=args.service_name)
+            else:
+                payload = session_to_otlp(meta, events, service_name=args.service_name)
             sys.stdout.write(json.dumps(payload, indent=2) + "\n")
             return 0
 
@@ -290,14 +301,33 @@ def cmd_export(args: argparse.Namespace) -> int:
                 key, val = h.split(":", 1)
                 headers[key.strip()] = val.strip()
 
-        ok = export_otlp(
-            store=store,
-            session_id=session_id,
-            endpoint=endpoint,
-            headers=headers,
-            service_name=args.service_name,
-        )
-        return 0 if ok else 1
+        if use_genai:
+            # Export using GenAI conventions
+            import urllib.request, urllib.error
+            meta = store.load_meta(session_id)
+            payload = session_to_otlp_genai(meta, events, service_name=args.service_name)
+            body = json.dumps(payload).encode("utf-8")
+            url = endpoint.rstrip("/") + "/v1/traces"
+            req_headers = {"Content-Type": "application/json"}
+            req_headers.update(headers)
+            req = urllib.request.Request(url, data=body, headers=req_headers, method="POST")
+            try:
+                with urllib.request.urlopen(req, timeout=30) as resp:
+                    ok = resp.status in (200, 202)
+                    sys.stderr.write(f"Exported {len(events)} events to {url} (HTTP {resp.status})\n")
+                    return 0 if ok else 1
+            except Exception as exc:
+                sys.stderr.write(f"OTLP GenAI export failed: {exc}\n")
+                return 1
+        else:
+            ok = export_otlp(
+                store=store,
+                session_id=session_id,
+                endpoint=endpoint,
+                headers=headers,
+                service_name=args.service_name,
+            )
+            return 0 if ok else 1
 
     return 0
 
@@ -477,7 +507,9 @@ def build_parser() -> argparse.ArgumentParser:
     # export
     p_export = sub.add_parser("export", help="export a session")
     p_export.add_argument("session_id", nargs="?", help="session ID or prefix")
-    p_export.add_argument("--format", choices=["json", "csv", "ndjson", "otlp"], default="json")
+    p_export.add_argument("--format", choices=["json", "csv", "ndjson", "otlp", "otlp-genai"],
+                          default="json",
+                          help="output format (otlp-genai uses strict OTel GenAI semantic conventions)")
     p_export.add_argument("--endpoint", help="OTLP collector URL (e.g. http://localhost:4318)")
     p_export.add_argument("--header", action="append", help="HTTP header for OTLP (e.g. 'x-honeycomb-team: KEY')")
     p_export.add_argument("--service-name", default="agent-trace", help="OTel service name (default: agent-trace)")