Common

1"""Shared helpers for the exploring-apm-traces skill scripts.
2
3When a script runs as `python3 scripts/foo.py FILE`, Python prepends the script's
4directory to sys.path, so `from _common import ...` resolves without any setup.
5"""
6
7import json
8
9
10SPAN_KIND = {0: "Unspecified", 1: "Internal", 2: "Server", 3: "Client", 4: "Producer", 5: "Consumer"}
11STATUS_CODE = {0: "Unset", 1: "OK", 2: "Error"}
12
13
14def is_zero_id(s):
15    return not s or set(s) == {"0"}
16
17
18def unwrap_text_envelope(raw):
19    # Claude Code persists large MCP tool results as [{"type": "text", "text": "<json>"}].
20    if isinstance(raw, list) and raw and isinstance(raw[0], dict) and raw[0].get("type") == "text":
21        return json.loads(raw[0]["text"])
22    return raw
23
24
25def load_trace_file(path):
26    with open(path) as f:
27        raw = json.load(f)
28    raw = unwrap_text_envelope(raw)
29    if isinstance(raw, dict):
30        for key in ("trace_spans", "spans", "results"):
31            if key in raw and isinstance(raw[key], list):
32                return raw[key]
33        return [raw]
34    return raw if isinstance(raw, list) else [raw]
35
36
37def fmt_duration(nanos):
38    if nanos is None:
39        return "?"
40    try:
41        n = int(nanos)
42    except (TypeError, ValueError):
43        return str(nanos)
44    if n >= 1_000_000_000:
45        return f"{n / 1_000_000_000:.2f}s"
46    if n >= 1_000_000:
47        return f"{n / 1_000_000:.1f}ms"
48    if n >= 1_000:
49        return f"{n / 1_000:.1f}\u00b5s"
50    return f"{n}ns"
51
52
53def truncate(s, max_len, show_total=False):
54    if max_len <= 0 or len(s) <= max_len:
55        return s
56    suffix = f"... [{len(s)} chars total]" if show_total else "..."
57    return s[:max_len] + suffix
58
59
60def is_root(span):
61    if span.get("is_root_span"):
62        return True
63    parent = span.get("parent_span_id") or ""
64    return is_zero_id(parent)