agentdynamics 0.4.0__py3-none-any.whl

agentdynamics/collectors/langsmith.py

@@ -0,0 +1,258 @@
+"""LangSmith / LangChain / LangGraph integration.
+
+Two ways in:
+  1. Drop-in receiver: point any LangChain/LangGraph app at AgentDynamics with
+         LANGSMITH_TRACING=true
+         LANGSMITH_ENDPOINT=http://<host>:8787/langsmith
+         LANGSMITH_API_KEY=<an AgentDynamics ingest key>
+     The LangSmith SDK then sends runs here (/runs/batch, /runs, PATCH /runs/{id}, /runs/multipart, /feedback).
+  2. Pull connector: read runs from an existing LangSmith project via its API (POST /runs/query).
+"""
+import json
+import time
+import urllib.request
+from datetime import datetime, timezone
+from email.parser import BytesParser
+from email.policy import default as email_policy
+
+
+def parse_time(v):
+    if v is None or v == "":
+        return None
+    if isinstance(v, (int, float)):
+        return v / 1000 if v > 1e12 else float(v)
+    s = str(v).replace("Z", "+00:00")
+    try:
+        d = datetime.fromisoformat(s)
+    except ValueError:
+        return None
+    if d.tzinfo is None:
+        d = d.replace(tzinfo=timezone.utc)
+    return d.timestamp()
+
+
+def merge(existing, update):
+    """Apply a LangSmith PATCH onto a stored run."""
+    out = dict(existing or {})
+    for k, v in (update or {}).items():
+        if v is None:
+            continue
+        if k == "_stub":
+            continue
+        if k == "extra" and isinstance(v, dict):
+            ex = dict(out.get("extra") or {})
+            for k2, v2 in v.items():
+                if k2 == "metadata" and isinstance(v2, dict):
+                    ex["metadata"] = {**(ex.get("metadata") or {}), **v2}
+                else:
+                    ex[k2] = v2
+            out["extra"] = ex
+        elif k == "feedback":
+            out["feedback"] = (out.get("feedback") or []) + list(v)
+        else:
+            out[k] = v
+    return out
+
+
+def _usage(outputs, run):
+    """Token usage from the many places LangChain puts it."""
+    it = ot = cr = cw = 0
+    stop = model = None
+    if run.get("prompt_tokens") or run.get("completion_tokens"):
+        it, ot = run.get("prompt_tokens") or 0, run.get("completion_tokens") or 0
+    o = outputs or {}
+    um = o.get("usage_metadata")
+    gens = o.get("generations") or []
+    flat = []
+    for g in gens:
+        flat.extend(g if isinstance(g, list) else [g])
+    for g in flat:
+        if not isinstance(g, dict):
+            continue
+        msg = g.get("message") or {}
+        kw = msg.get("kwargs") if isinstance(msg, dict) and "kwargs" in msg else msg
+        kw = kw or {}
+        um = um or kw.get("usage_metadata")
+        rm = kw.get("response_metadata") or {}
+        gi = g.get("generation_info") or {}
+        stop = stop or rm.get("stop_reason") or rm.get("finish_reason") or gi.get("finish_reason")
+        model = model or rm.get("model") or rm.get("model_name")
+    if um:
+        it = um.get("input_tokens") or it
+        ot = um.get("output_tokens") or ot
+        det = um.get("input_token_details") or {}
+        cr = det.get("cache_read") or 0
+        cw = det.get("cache_creation") or 0
+    tu = (o.get("llm_output") or {}).get("token_usage") or (o.get("llm_output") or {}).get("usage") or {}
+    if tu and not (it or ot):
+        it = tu.get("prompt_tokens") or tu.get("input_tokens") or 0
+        ot = tu.get("completion_tokens") or tu.get("output_tokens") or 0
+    return it, ot, cr, cw, stop, model
+
+
+KIND = {"llm": "llm", "tool": "tool", "retriever": "retriever", "embedding": "embedding", "chain": "chain", "prompt": "chain", "parser": "chain"}
+
+
+def to_span(r):
+    """LangSmith run dict -> canonical span (None for feedback-only stubs whose run hasn't arrived yet)."""
+    if r.get("_stub") and not r.get("run_type"):
+        return None
+    extra = r.get("extra") or {}
+    md = {**(extra.get("metadata") or {}), **(r.get("metadata") or {})}
+    inv = extra.get("invocation_params") or {}
+    run_type = r.get("run_type") or "chain"
+    kind = KIND.get(run_type, "chain")
+    node = md.get("langgraph_node")
+    if kind == "chain" and node and r.get("name") == node:
+        kind = "node"
+    if r.get("name") in ("__interrupt__",) or "GraphInterrupt" in str(r.get("error") or ""):
+        kind = "human"
+    it = ot = cr = cw = 0
+    stop = model_out = None
+    if kind in ("llm", "embedding"):
+        it, ot, cr, cw, stop, model_out = _usage(r.get("outputs"), r)
+    start = parse_time(r.get("start_time"))
+    ttft = None
+    for ev in r.get("events") or []:
+        if ev.get("name") == "new_token" and start:
+            t = parse_time(ev.get("time"))
+            if t:
+                ttft = max(0.0, (t - start) * 1000)
+            break
+    docs = None
+    if kind == "retriever":
+        d = (r.get("outputs") or {}).get("documents")
+        docs = len(d) if isinstance(d, list) else None
+    fb = []
+    for k, v in (r.get("feedback_stats") or {}).items():
+        if isinstance(v, dict) and v.get("avg") is not None:
+            fb.append({"key": k, "score": v["avg"]})
+    fb += [f for f in (r.get("feedback") or []) if f.get("score") is not None]
+    err = r.get("error")
+    return {
+        "trace_id": str(r.get("trace_id") or r.get("id")), "span_id": str(r.get("id")),
+        "parent_id": str(r["parent_run_id"]) if r.get("parent_run_id") else None,
+        "name": r.get("name"), "kind": kind, "start": start, "end": parse_time(r.get("end_time")),
+        "status": "error" if err else ("ok" if r.get("end_time") else "unset"), "error": err,
+        "model": md.get("ls_model_name") or inv.get("model") or inv.get("model_name") or model_out,
+        "provider": md.get("ls_provider"), "input_tokens": it, "output_tokens": ot, "cache_read": cr, "cache_write": cw,
+        "cost": r.get("total_cost") if kind == "llm" and r.get("total_cost") is not None else None,
+        "stop_reason": stop, "ttft_ms": ttft, "input": r.get("inputs"), "output": r.get("outputs"),
+        "node": node, "agent": md.get("agent_name") or md.get("lc_agent_name"),
+        "workflow": None,
+        "project": r.get("session_name") or md.get("project"), "environment": md.get("environment") or md.get("env"),
+        "session_id": md.get("thread_id") or md.get("session_id") or md.get("conversation_id"),
+        "user_id": md.get("user_id"), "framework": "langgraph" if (node or md.get("langgraph_step") is not None) else "langchain",
+        "docs": docs, "feedback": fb, "tags": r.get("tags") or [], "source": "langsmith",
+    }
+
+
+# ---------------------------------------------------------------- receiver payloads
+
+def parse_batch(body):
+    d = json.loads(body or b"{}")
+    return d.get("post") or [], d.get("patch") or []
+
+
+def parse_multipart(body, content_type):
+    """/runs/multipart: parts named post.<id>, post.<id>.inputs, patch.<id>.outputs, feedback.<id> ..."""
+    msg = BytesParser(policy=email_policy).parsebytes(b"Content-Type: " + content_type.encode() + b"\r\n\r\n" + body)
+    posts, patches, feedback = {}, {}, []
+    for part in msg.iter_parts():
+        name = part.get_param("name", header="content-disposition") or ""
+        try:
+            data = json.loads(part.get_content() if part.get_content_type().startswith("text") else part.get_payload(decode=True))
+        except (ValueError, TypeError):
+            continue
+        bits = name.split(".")
+        if len(bits) < 2:
+            continue
+        op, rid = bits[0], bits[1]
+        target = posts if op == "post" else patches if op == "patch" else None
+        if op == "feedback":
+            feedback.append(data)
+            continue
+        if target is None:
+            continue
+        if len(bits) == 2:
+            target.setdefault(rid, {}).update(data)
+        else:
+            target.setdefault(rid, {})[bits[2]] = data
+    for rid, r in list(posts.items()) + list(patches.items()):
+        r.setdefault("id", rid)
+    return list(posts.values()), list(patches.values()), feedback
+
+
+def zstd_available():
+    try:
+        import zstandard  # noqa: F401  (installed alongside recent langsmith SDKs)
+        return True
+    except ImportError:
+        return False
+
+
+def zstd_decompress(body):
+    import io
+
+    import zstandard
+    # the SDK streams frames without a content size, so read through a stream reader
+    return zstandard.ZstdDecompressor().stream_reader(io.BytesIO(body)).read()
+
+
+def info():
+    """What we tell the LangSmith SDK (GET /info). With zstandard available we accept compressed multipart
+    (about 10x smaller uploads); otherwise the SDK falls back to plain JSON /runs/batch."""
+    z = zstd_available()
+    return {
+        "version": "agentdynamics-0.4",
+        "batch_ingest_config": {"scale_up_qsize_trigger": 1000, "scale_up_nthreads_limit": 16, "scale_down_nempty_trigger": 4,
+                                "size_limit": 100, "size_limit_bytes": 20_971_520, "use_multipart_endpoint": z},
+        "instance_flags": {"zstd_compression_enabled": z},
+    }
+
+
+INFO = info()
+
+
+# ---------------------------------------------------------------- pull connector
+
+class LangSmithPuller:
+    """Incrementally pull runs from a LangSmith project."""
+
+    def __init__(self, cfg, state):
+        import os
+        self.api = (cfg.get("api_url") or os.environ.get("LANGSMITH_ENDPOINT") or "https://api.smith.langchain.com").rstrip("/")
+        self.key = os.environ.get(cfg.get("api_key_env", "LANGSMITH_API_KEY"), "")
+        self.project = cfg["project"]
+        self.state = state  # dict persisted by the engine
+        self.lookback = float(cfg.get("lookback_hours", 24)) * 3600
+
+    def _req(self, method, path, body=None, params=""):
+        req = urllib.request.Request(f"{self.api}{path}{params}", method=method, data=json.dumps(body).encode() if body is not None else None,
+                                     headers={"x-api-key": self.key, "Content-Type": "application/json", "Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=30) as r:
+            return json.loads(r.read() or b"null")
+
+    def pull(self, max_runs=5000):
+        from urllib.parse import quote
+        if not self.state.get("session_id"):
+            ses = self._req("GET", "/sessions", params=f"?name={quote(self.project)}&limit=1")
+            if not ses:
+                raise RuntimeError(f"LangSmith project '{self.project}' not found")
+            self.state["session_id"] = ses[0]["id"]
+        since = self.state.get("since") or (time.time() - self.lookback)
+        body = {"session": [self.state["session_id"]], "start_time": datetime.fromtimestamp(since, timezone.utc).isoformat(), "limit": 100}
+        runs, newest = [], since
+        while len(runs) < max_runs:
+            res = self._req("POST", "/runs/query", body) or {}
+            batch = res.get("runs") or []
+            runs.extend(batch)
+            for r in batch:
+                newest = max(newest, parse_time(r.get("start_time")) or 0)
+            nxt = (res.get("cursors") or {}).get("next")
+            if not batch or not nxt:
+                break
+            body["cursor"] = nxt
+        # re-read a small window next time so runs that were still open get their end state
+        self.state["since"] = max(since, newest - 600)
+        return runs

agentdynamics/collectors/otlp.py

@@ -0,0 +1,349 @@
+"""OpenTelemetry (OTLP/HTTP) trace receiver: JSON and protobuf encodings, zero dependencies.
+
+Maps the three agent semantic conventions in use today onto canonical spans:
+  * OpenTelemetry GenAI semconv (gen_ai.*)       - OpenAI Agents SDK, Strands, Semantic Kernel, PydanticAI, ...
+  * OpenInference (openinference.span.kind, llm.*) - Arize Phoenix instrumentors: LangChain/LangGraph, LlamaIndex,
+                                                    CrewAI, DSPy, AutoGen, OpenAI, Anthropic, Bedrock, ...
+  * OpenLLMetry / Traceloop (traceloop.*)         - Traceloop SDK instrumentors
+plus LangSmith's OTel attributes (langsmith.*) and LangGraph metadata (langgraph_node, langgraph_step).
+"""
+import json
+import struct
+
+# ---------------------------------------------------------------- protobuf wire decoding
+
+def _varint(buf, i):
+    shift = res = 0
+    while True:
+        b = buf[i]
+        i += 1
+        res |= (b & 0x7F) << shift
+        if not b & 0x80:
+            return res, i
+        shift += 7
+
+
+def _fields(buf):
+    """Yield (field_number, wire_type, value) for a protobuf message."""
+    i, n = 0, len(buf)
+    while i < n:
+        key, i = _varint(buf, i)
+        fn, wt = key >> 3, key & 7
+        if wt == 0:
+            v, i = _varint(buf, i)
+        elif wt == 1:
+            v = buf[i:i + 8]
+            i += 8
+        elif wt == 2:
+            ln, i = _varint(buf, i)
+            v = buf[i:i + ln]
+            i += ln
+        elif wt == 5:
+            v = buf[i:i + 4]
+            i += 4
+        else:
+            raise ValueError(f"unsupported wire type {wt}")
+        yield fn, wt, v
+
+
+def _any_value(buf):
+    for fn, wt, v in _fields(buf):
+        if fn == 1:
+            return v.decode("utf-8", "replace")
+        if fn == 2:
+            return bool(v)
+        if fn == 3:
+            return v - (1 << 64) if v >= 1 << 63 else v
+        if fn == 4:
+            return struct.unpack("<d", v)[0]
+        if fn == 5:
+            return [_any_value(x) for f2, _, x in _fields(v) if f2 == 1]
+        if fn == 6:
+            return dict(_kv(x) for f2, _, x in _fields(v) if f2 == 1)
+        if fn == 7:
+            return v.hex()
+    return None
+
+
+def _kv(buf):
+    k, val = "", None
+    for fn, _, v in _fields(buf):
+        if fn == 1:
+            k = v.decode("utf-8", "replace")
+        elif fn == 2:
+            val = _any_value(v)
+    return k, val
+
+
+def _span_pb(buf):
+    s = {"attributes": {}, "events": [], "status": {}}
+    for fn, wt, v in _fields(buf):
+        if fn == 1:
+            s["traceId"] = v.hex()
+        elif fn == 2:
+            s["spanId"] = v.hex()
+        elif fn == 4:
+            s["parentSpanId"] = v.hex()
+        elif fn == 5:
+            s["name"] = v.decode("utf-8", "replace")
+        elif fn == 6:
+            s["kind"] = v
+        elif fn == 7:
+            s["startTimeUnixNano"] = struct.unpack("<Q", v)[0]
+        elif fn == 8:
+            s["endTimeUnixNano"] = struct.unpack("<Q", v)[0]
+        elif fn == 9:
+            k, val = _kv(v)
+            s["attributes"][k] = val
+        elif fn == 11:
+            ev = {"attributes": {}}
+            for f2, _, x in _fields(v):
+                if f2 == 1:
+                    ev["timeUnixNano"] = struct.unpack("<Q", x)[0]
+                elif f2 == 2:
+                    ev["name"] = x.decode("utf-8", "replace")
+                elif f2 == 3:
+                    k, val = _kv(x)
+                    ev["attributes"][k] = val
+            s["events"].append(ev)
+        elif fn == 15:
+            for f2, _, x in _fields(v):
+                if f2 == 2:
+                    s["status"]["message"] = x.decode("utf-8", "replace")
+                elif f2 == 3:
+                    s["status"]["code"] = x
+    return s
+
+
+def decode_protobuf(body):
+    """ExportTraceServiceRequest bytes -> list of (resource_attrs, scope_name, span_dict)."""
+    out = []
+    for fn, _, rs in _fields(body):
+        if fn != 1:
+            continue
+        res_attrs, scopes = {}, []
+        for f2, _, v in _fields(rs):
+            if f2 == 1:
+                for f3, _, kv in _fields(v):
+                    if f3 == 1:
+                        k, val = _kv(kv)
+                        res_attrs[k] = val
+            elif f2 == 2:
+                scopes.append(v)
+        for ss in scopes:
+            scope = ""
+            for f3, _, v in _fields(ss):
+                if f3 == 1:
+                    for f4, _, x in _fields(v):
+                        if f4 == 1:
+                            scope = x.decode("utf-8", "replace")
+                elif f3 == 2:
+                    out.append((res_attrs, scope, _span_pb(v)))
+    return out
+
+
+# ---------------------------------------------------------------- JSON decoding
+
+def _json_any(v):
+    if not isinstance(v, dict):
+        return v
+    for k, val in v.items():
+        if k == "stringValue":
+            return val
+        if k == "boolValue":
+            return bool(val)
+        if k == "intValue":
+            return int(val)
+        if k == "doubleValue":
+            return float(val)
+        if k == "arrayValue":
+            return [_json_any(x) for x in (val or {}).get("values", [])]
+        if k == "kvlistValue":
+            return {x["key"]: _json_any(x.get("value")) for x in (val or {}).get("values", [])}
+        if k == "bytesValue":
+            return val
+    return None
+
+
+def _json_attrs(lst):
+    return {a["key"]: _json_any(a.get("value")) for a in lst or []}
+
+
+def _hexid(v):
+    """OTLP/JSON ids are hex strings; some exporters send base64. Normalize to hex."""
+    if not v:
+        return None
+    if all(c in "0123456789abcdefABCDEF" for c in v):
+        return v.lower()
+    import base64
+    try:
+        return base64.b64decode(v).hex()
+    except ValueError:
+        return v
+
+
+def decode_json(doc):
+    out = []
+    for rs in doc.get("resourceSpans", []):
+        res_attrs = _json_attrs((rs.get("resource") or {}).get("attributes"))
+        for ss in rs.get("scopeSpans", []) or rs.get("instrumentationLibrarySpans", []):
+            scope = (ss.get("scope") or ss.get("instrumentationLibrary") or {}).get("name", "")
+            for sp in ss.get("spans", []):
+                out.append((res_attrs, scope, {
+                    "traceId": _hexid(sp.get("traceId")), "spanId": _hexid(sp.get("spanId")),
+                    "parentSpanId": _hexid(sp.get("parentSpanId")), "name": sp.get("name"), "kind": sp.get("kind"),
+                    "startTimeUnixNano": int(sp.get("startTimeUnixNano") or 0), "endTimeUnixNano": int(sp.get("endTimeUnixNano") or 0),
+                    "attributes": _json_attrs(sp.get("attributes")),
+                    "events": [{"name": e.get("name"), "timeUnixNano": int(e.get("timeUnixNano") or 0), "attributes": _json_attrs(e.get("attributes"))}
+                               for e in sp.get("events", [])],
+                    "status": {"code": {"STATUS_CODE_ERROR": 2, "STATUS_CODE_OK": 1}.get(sp.get("status", {}).get("code"), sp.get("status", {}).get("code")),
+                               "message": sp.get("status", {}).get("message")},
+                }))
+    return out
+
+
+# ---------------------------------------------------------------- semantic-convention mapping
+
+def _g(a, *keys):
+    for k in keys:
+        v = a.get(k)
+        if v not in (None, "", []):
+            return v
+    return None
+
+
+def _num(v):
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _metadata(a):
+    md = a.get("metadata")
+    if isinstance(md, str):
+        try:
+            md = json.loads(md)
+        except ValueError:
+            md = {}
+    out = dict(md) if isinstance(md, dict) else {}
+    for k, v in a.items():
+        if k.startswith("metadata.") or k.startswith("langsmith.metadata."):
+            out[k.split("metadata.", 1)[1]] = v
+    return out
+
+
+OI_KIND = {"LLM": "llm", "TOOL": "tool", "CHAIN": "chain", "AGENT": "agent", "RETRIEVER": "retriever", "EMBEDDING": "embedding",
+           "RERANKER": "retriever", "GUARDRAIL": "guardrail", "EVALUATOR": "evaluator"}
+GENAI_OP = {"chat": "llm", "text_completion": "llm", "generate_content": "llm", "completion": "llm", "execute_tool": "tool",
+            "invoke_agent": "agent", "create_agent": "agent", "embeddings": "embedding", "handoff": "handoff"}
+
+
+def _doc_count(a, kind):
+    """Retrieved documents: explicit count, a list, or OpenInference's flattened retrieval.documents.<i>.* keys."""
+    if kind != "retriever":
+        return None
+    if _num(a.get("retrieval.documents.count")) is not None:
+        return int(_num(a["retrieval.documents.count"]))
+    if isinstance(a.get("retrieval.documents"), list):
+        return len(a["retrieval.documents"])
+    idx = {k.split(".")[2] for k in a if k.startswith("retrieval.documents.") and k.split(".")[2].isdigit()}
+    return len(idx)
+
+
+def map_span(res, scope, sp):
+    a = sp["attributes"]
+    md = _metadata(a)
+    oi = str(a.get("openinference.span.kind") or "").upper()
+    tl = str(a.get("traceloop.span.kind") or "").lower()
+    ls = str(a.get("langsmith.span.kind") or "").lower()
+    op = str(a.get("gen_ai.operation.name") or "").lower()
+    if oi in OI_KIND:
+        kind = OI_KIND[oi]
+    elif op in GENAI_OP:
+        kind = GENAI_OP[op]
+    elif ls:
+        kind = {"llm": "llm", "tool": "tool", "retriever": "retriever", "embedding": "embedding", "chain": "chain", "prompt": "chain", "parser": "chain"}.get(ls, "chain")
+    elif tl:
+        kind = {"workflow": "chain", "task": "chain", "agent": "agent", "tool": "tool"}.get(tl, "chain")
+    elif _g(a, "gen_ai.request.model", "llm.model_name", "gen_ai.response.model"):
+        kind = "llm"
+    elif a.get("gen_ai.tool.name") or a.get("tool.name"):
+        kind = "tool"
+    else:
+        kind = "span"
+    if md.get("langgraph_node") and kind == "chain" and sp.get("name") == md.get("langgraph_node"):
+        kind = "node"
+
+    status = sp.get("status") or {}
+    err = None
+    if status.get("code") == 2:
+        err = status.get("message") or "error"
+    for ev in sp.get("events", []):
+        if ev.get("name") == "exception":
+            ea = ev.get("attributes", {})
+            err = f"{ea.get('exception.type', '')}: {ea.get('exception.message', '')}".strip(": ") or err
+    finish = _g(a, "gen_ai.response.finish_reasons", "llm.finish_reason", "gen_ai.response.finish_reason")
+    if isinstance(finish, list):
+        finish = finish[0] if finish else None
+    ttft = _num(_g(a, "gen_ai.response.time_to_first_token", "gen_ai.server.time_to_first_token", "llm.time_to_first_token"))
+    if ttft is not None and ttft < 100:  # seconds -> ms
+        ttft *= 1000
+    start = sp["startTimeUnixNano"] / 1e9 if sp.get("startTimeUnixNano") else None
+    end = sp["endTimeUnixNano"] / 1e9 if sp.get("endTimeUnixNano") else None
+    inp = _g(a, "input.value", "gen_ai.prompt", "traceloop.entity.input", "gen_ai.input.messages", "langsmith.inputs", "gen_ai.prompt.0.content",
+             "gen_ai.tool.call.arguments")
+    out = _g(a, "output.value", "gen_ai.completion", "traceloop.entity.output", "gen_ai.output.messages", "langsmith.outputs",
+             "gen_ai.completion.0.content", "gen_ai.tool.call.result")
+    name = sp.get("name")
+    if kind == "tool":
+        name = _g(a, "gen_ai.tool.name", "tool.name") or name
+    fw = "otel"
+    if oi:
+        fw = "openinference"
+    elif tl:
+        fw = "openllmetry"
+    elif ls:
+        fw = "langsmith-otel"
+    elif op:
+        fw = "genai-semconv"
+    if md.get("langgraph_node") or "langgraph" in (scope or "").lower():
+        fw = "langgraph"
+    feedback = []
+    for k, v in a.items():
+        if k.startswith("feedback.") and _num(v) is not None:
+            feedback.append({"key": k[9:], "score": _num(v)})
+    return {
+        "trace_id": sp.get("traceId"), "span_id": sp.get("spanId"), "parent_id": sp.get("parentSpanId") or None,
+        "name": name, "kind": kind, "start": start, "end": end, "status": "error" if err else "ok", "error": err,
+        "model": _g(a, "gen_ai.response.model", "gen_ai.request.model", "llm.model_name", "llm.request.model"),
+        "provider": _g(a, "gen_ai.system", "gen_ai.provider.name", "llm.provider", "llm.system"),
+        "input_tokens": _num(_g(a, "gen_ai.usage.input_tokens", "gen_ai.usage.prompt_tokens", "llm.token_count.prompt", "llm.usage.prompt_tokens")) or 0,
+        "output_tokens": _num(_g(a, "gen_ai.usage.output_tokens", "gen_ai.usage.completion_tokens", "llm.token_count.completion", "llm.usage.completion_tokens")) or 0,
+        "cache_read": _num(_g(a, "gen_ai.usage.cache_read.input_tokens", "gen_ai.usage.cache_read_input_tokens", "llm.token_count.prompt_details.cache_read",
+                             "gen_ai.usage.input_tokens.cached")) or 0,
+        "cache_write": _num(_g(a, "gen_ai.usage.cache_creation.input_tokens", "gen_ai.usage.cache_creation_input_tokens",
+                              "llm.token_count.prompt_details.cache_write")) or 0,
+        "thinking_tokens": _num(_g(a, "gen_ai.usage.reasoning_tokens", "llm.token_count.completion_details.reasoning")) or 0,
+        "cost": _num(_g(a, "gen_ai.usage.cost", "llm.cost.total", "langsmith.total_cost")),
+        "stop_reason": finish, "ttft_ms": ttft, "input": inp, "output": out,
+        "node": md.get("langgraph_node") or a.get("langgraph.node") or a.get("graph.node.id"),
+        "agent": _g(a, "gen_ai.agent.name", "agent.name", "graph.node.parent_id") or md.get("agent_name"),
+        "workflow": _g(a, "traceloop.workflow.name", "gen_ai.workflow.name") or None,
+        "project": _g(res, "service.name") if _g(res, "service.name") not in (None, "unknown_service") else md.get("project"),
+        "environment": _g(res, "deployment.environment.name", "deployment.environment") or md.get("environment"),
+        "session_id": _g(a, "session.id", "gen_ai.conversation.id", "langsmith.trace.session_id") or md.get("thread_id") or md.get("session_id"),
+        "user_id": _g(a, "user.id", "enduser.id") or md.get("user_id"),
+        "framework": fw, "docs": _doc_count(a, kind),
+        "feedback": feedback, "tags": a.get("tag.tags") if isinstance(a.get("tag.tags"), list) else [],
+        "source": "otlp",
+    }
+
+
+def parse_request(body, content_type="application/json"):
+    """Return canonical spans from an OTLP/HTTP export request body."""
+    if "protobuf" in (content_type or "") or (body[:1] not in (b"{", b"[") and body):
+        records = decode_protobuf(body)
+    else:
+        records = decode_json(json.loads(body))
+    return [map_span(r, sc, sp) for r, sc, sp in records if sp.get("traceId") and sp.get("spanId")]