分布式链路追踪 Span/Trace API

OnePath 的分布式链路追踪（W3C Trace Context 兼容）API 参考。提供 Span 的创建、属性、状态、事件，以及 trace 上下文的手动传播。本页仅覆盖 tracing / span 部分，指标 API 见 指标收集。

两个变体均支持

tracing 子系统在 full 与 tiny 两个变体下行为一致，无需额外配置。

指南视角（自动埋点覆盖范围、attachment TLV 布局、多跳透传、限制）见 分布式追踪与指标。

数据类型

onepath_span_t

typedef struct onepath_span *onepath_span_t;

活跃的 span 句柄，由 onepath_span_start() 返回，onepath_span_end() 释放。不透明类型，用户不可解引用。

onepath_trace_ctx_t

typedef struct {
    uint8_t version;       /* 当前为 0x00 */
    uint8_t trace_id[16];  /* 全局 trace id, 全零表示无效 */
    uint8_t span_id[8];    /* 父 span id, 全零表示无效 */
    uint8_t flags;         /* bit0 = sampled */
} onepath_trace_ctx_t;

W3C Trace Context 二进制表示，对应 traceparent：ver (1B) + trace_id (16B) + span_id (8B) + flags (1B)，共 26 字节。trace_id / span_id 全零表示无效（无活跃 span）。

选项与初始化

onepath_trace_opts_t

typedef struct {
    const char *service_name;   /* 服务名, 记录到每个 span 的 resource */
    const char *ndjson_path;    /* NDJSON 输出路径, NULL 禁用导出 */
    double      sample_ratio;   /* 头部采样率 [0.0, 1.0], 1.0=全采, 0.0=不采 */
    size_t      ring_capacity;  /* 内部环形缓冲容量 (span 数), 0=默认 1024 */
} onepath_trace_opts_t;

ONEPATH_TRACE_OPTS_DEFAULT

#define ONEPATH_TRACE_OPTS_DEFAULT { NULL, NULL, 0.0, 0 }

onepath_trace_opts_t 的默认初始化宏。

onepath_trace_init

int onepath_trace_init(const onepath_trace_opts_t *opts);

初始化追踪子系统。

• 参数：opts — 选项指针，传 NULL 采用全默认值；各字段为 NULL / 0 时自动从环境变量读取对应配置
• 返回值：ONEPATH_OK 成功
• 注意：可多次调用，第二次起返回 ONEPATH_OK 但不重新初始化；onepath_trace_shutdown() 后允许再次 init。首次 onepath_span_start() 时若 ONEPATH_TRACE_ENABLE=1 会自动 lazy init

onepath_trace_shutdown

void onepath_trace_shutdown(void);

关闭追踪子系统，刷新 exporter 并释放资源。

函数

onepath_span_start

onepath_span_t onepath_span_start(const char *name, int kind,
                                  const onepath_trace_ctx_t *parent);

开始一个新 span。

• 参数：
  • name — span 名
  • kind — span 类型，取 ONEPATH_SPAN_KIND_*
  • parent — 显式父上下文，可为 NULL
• 返回值：span 句柄；若追踪未启用或采样不命中，返回 NULL（后续所有 API 均 no-op）
• 注意：parent 为 NULL 且当前线程 span 栈非空时，自动以栈顶为父；都无父则创建新 trace。采样决策仅在创建新 trace 时做一次，后续子 span 继承父的 sampled flag。新 span 自动压入当前线程的 span 栈，onepath_span_end() 时出栈

onepath_span_end

void onepath_span_end(onepath_span_t span);

结束 span 并入队导出，同时从当前线程 span 栈出栈。

• 参数：span — span 句柄，可为 NULL（no-op）

onepath_span_set_attr_str

void onepath_span_set_attr_str(onepath_span_t span, const char *key, const char *value);

设置字符串属性。

• 参数：span — span 句柄；key — 属性键；value — 属性值

onepath_span_set_attr_i64

void onepath_span_set_attr_i64(onepath_span_t span, const char *key, int64_t value);

设置整数属性。

• 参数：span — span 句柄；key — 属性键；value — 属性值

onepath_span_set_attr_f64

void onepath_span_set_attr_f64(onepath_span_t span, const char *key, double value);

设置浮点属性。

• 参数：span — span 句柄；key — 属性键；value — 属性值

onepath_span_set_status

void onepath_span_set_status(onepath_span_t span, int status, const char *msg);

标记 span 状态（OK / ERROR）。

• 参数：
  • span — span 句柄
  • status — 取 ONEPATH_SPAN_STATUS_*
  • msg — 可选错误描述，可为 NULL

onepath_span_add_event

void onepath_span_add_event(onepath_span_t span, const char *name);

添加事件（无时长，仅时间戳 + 名称）。

• 参数：span — span 句柄；name — 事件名

onepath_trace_current_ctx

int onepath_trace_current_ctx(onepath_trace_ctx_t *out);

获取当前线程栈顶 span 的上下文。

• 参数：out — 输出 ctx（无活跃 span 时写全零）
• 返回值：1 有活跃 span，0 无

onepath_trace_ctx_from_string

int onepath_trace_ctx_from_string(const char *s, onepath_trace_ctx_t *out);

把 W3C traceparent 字符串解析为二进制 ctx。

• 参数：s — traceparent 字符串（NUL 结尾），格式为 "00-<32hex>-<16hex>-<2hex>"（共 55 字符）；out — 解析结果
• 返回值：ONEPATH_OK 成功，ONEPATH_ERR_PARAM 格式错误

onepath_trace_ctx_to_string

int onepath_trace_ctx_to_string(const onepath_trace_ctx_t *ctx, char *out);

把二进制 ctx 格式化为 W3C traceparent 字符串。

• 参数：ctx — 二进制 ctx；out — 至少 56 字节缓冲
• 返回值：ONEPATH_OK

常量与枚举

Span 类型（ONEPATH_SPAN_KIND_*）

OpenTelemetry SpanKind 子集。

常量	值	含义
ONEPATH_SPAN_KIND_INTERNAL	0	内部逻辑
ONEPATH_SPAN_KIND_PRODUCER	1	发送消息
ONEPATH_SPAN_KIND_CONSUMER	2	接收消息
ONEPATH_SPAN_KIND_CLIENT	3	发出 RPC（get / request）
ONEPATH_SPAN_KIND_SERVER	4	处理 RPC（响应端 / responder）

Span 状态（ONEPATH_SPAN_STATUS_*）

常量	值
ONEPATH_SPAN_STATUS_UNSET	0
ONEPATH_SPAN_STATUS_OK	1
ONEPATH_SPAN_STATUS_ERROR	2

内存与所有权

• onepath_span_t 由库内部管理：onepath_span_start() 创建并压栈，onepath_span_end() 出栈并入队导出，用户不直接释放。
• 传入 NULL 的 span 句柄给任意 span API 均为 no-op，安全。
• onepath_trace_ctx_t 为值类型，可自由拷贝；跨线程 / 异步传播 trace 时通常先 onepath_trace_current_ctx() 抓取一份 ctx，再在目标线程以其为 parent 调用 onepath_span_start()。
• 追踪未启用或采样不命中时，onepath_span_start() 返回 NULL，整套 API 退化为零开销 no-op，无需在调用点做条件判断。
• onepath_trace_init() 的 opts 仅在调用期间被读取，调用返回后即可释放或复用，库不持有其指针。

相关指南

• 分布式追踪与指标 — 自动埋点覆盖范围、attachment TLV 布局、多跳透传、限制与注意事项