端到端 Trace 指南

把一次完整的用户操作（浏览器 / App → 后端服务 → 下游服务）串成一条因果链，存进 Argus， 在 Console 用瀑布图查看。Argus Trace 100% 基于 W3C Trace Context（traceparent 头）。

关键概念

一个 trace 是一次用户操作引发的因果链，由多个 span 组成树状结构。每个 span 有 trace_id（整条链路共享）、span_id（本节点）、parent_span_id（父节点）。traceparent 头把 这三者在服务间传播：

traceparent: 00-<32hex trace_id>-<16hex span_id>-<2hex flags>
                  └─ 整条链路共享     └─ 本 span      └─ 01=采样 / 00=不采

一条端到端 trace 长这样：

trace_id = abc123...
└─ span: client.http  "POST /api/order"     (Web / App 端 SDK，出站注入)
   └─ span: server.http "POST /api/order"   (你的 Go / Node 服务，中间件继承)
      ├─ span: internal "charge-card"        (手动子 span)
      └─ span: client.http "POST payments"   (出站注入，传给下游)
         └─ span: server.http ...            (下游服务继承)

三步打通

const headers = Argus.traceHeaders(); // { traceparent: "00-<trace>-<span>-01" }

// Go
http.ListenAndServe(":8080", client.Middleware(mux))

// Node（Express）
app.use(argus.middleware());

// Go
req.Header.Set("traceparent", argus.TraceparentFromContext(ctx))

// Node
fetch(url, { headers: { ...argus.traceHeaders() } });

采样一致性

头部采样按 trace_id 做 FNV-1a 一致性 hash，Web / Go / Node SDK 同算法、同向量——保证 整条 trace 要么全采、要么全弃，不会出现残缺链路。status=error 的 span 强制保留（即使采样 率很低也不丢错误链路）。

后端 SDK 用 sampleRate / SampleRate 配置（[0,1]，0/缺省=全采）。

日志 ↔ Trace 关联

后端日志若处于 active span 上下文，会自动带上 trace_id：

client.Info(ctx, "order received", map[string]string{"user_id": "u-42"})
// → 该日志带 trace_id，可在 Console 按链路聚合「后端 + 端上」日志

客户后端日志 shipper 也可显式带 trace_id 或透传 traceparent，把同一请求横跨多服务的日志聚到 一起。详见 后端日志接入 。

Console 瀑布图

接入后，在 Console 的 /traces 页：

1. Trace 列表：按 project / 时间 / user_id / session_id / status / operation / duration 过滤。
2. Trace 详情（瀑布图）：按父子关系缩进，每个 span 是一条时间轴长条，长度 ∝ 耗时，颜色编码：
   • 🔴 红 = status=error
   • 🔵 蓝 = kind=client（出站调用）
   • 🟢 绿 = kind=server（服务端处理）
   • ⚪ 灰 = 其他（internal 等）
3. 点 span 看 attributes / status，定位慢在哪一跳。

端到端验证（本地）

# 1) 起后端服务（Go 或 Node 示例）
cd examples/go-backend-demo
ARGUS_DSN='argus://demo-public:demo-secret@localhost:4318/demo' go run .
 
# 2) 模拟端上 SDK 带 traceparent 进来
curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
     http://localhost:8080/api/order

在 Console /traces 用该 trace_id（4bf92f3577b34da6a3ce929d0e0e4736）即可看到这条链路。