W3C Trace Context 傳播

observability 追蹤器與 agent_trace 的 span 都不帶任何 ID,因此一次 HTTP 呼叫一端的 span 無法與它在另一端觸發的工作關聯起來。本功能加入 W3C Trace Context 標準 —— 產生、解析並傳播 traceparent / tracestate 標頭,讓 span、日誌與下游服務共享同一條 trace 與 span 血緣。

純標準函式庫(os / re);不匯入 PySide6。ID 產生可注入 RNG,因此 trace 與 span ID 在測試中 具決定性。

無頭 API

from je_auto_control import (
    new_root_context, child_context, inject_context, extract_context,
    parse_traceparent, format_traceparent,
)

# 開啟一條 trace 並傳播到外送請求:
ctx = new_root_context()
headers = inject_context({"accept": "application/json"}, ctx)
# headers["traceparent"] == "00-<32 hex>-<16 hex>-01"

# 接收端延續同一條 trace:
parent = extract_context(request_headers)
if parent is not None:
    span = child_context(parent)        # 相同 trace_id,新的 span_id

SpanContext 是不可變的(trace_id、span_id、trace_flags、tracestate)組合。 new_root_context 鑄造新 trace;``child_context`` 保留 trace id 與繼承狀態但配置新的 span id。 parse_traceparent / format_traceparent 來回轉換 version-00 標頭(對錯誤版本、格式不符或全零 ID 拋出 TraceContextError);``parse_tracestate`` / format_tracestate 處理 vendor 清單。 inject_context 寫入標頭;``extract_context`` 將其讀回(不分大小寫)。

執行器命令

AC_trace_inject 把 context 傳播到外送 headers —— 帶 traceparent 時衍生該父節點的子 span, 否則開啟新的 root —— 回傳 {headers, traceparent, trace_id, span_id}。AC_trace_extract 從請求 headers 讀回 context,回傳 {context}``(無 ``traceparent 時為 null)。兩者皆以 MCP 工具 (ac_trace_inject / ac_trace_extract)以及 Script Builder 中 Data 分類下的命令提供。