环境变量总览

OnePath 的链路追踪与指标功能完全由环境变量控制，用户代码无需任何修改、无需重新编译。本页汇总全部变量；追踪 / 指标的工作机制、自动埋点通路与多跳透传等细节，见 专有场景 · 链路追踪。

链路追踪（Tracing）

变量	作用	默认值
ONEPATH_TRACE_ENABLE	追踪总开关；设为 1 启用，未启用时所有追踪调用退化为 no-op、零开销	0
ONEPATH_TRACE_SAMPLE_RATIO	头部采样率，取值 [0.0, 1.0]；1.0 = 全采，0.0 = 仅维护线程调用栈不导出	0.0
ONEPATH_TRACE_NDJSON_PATH	NDJSON 导出文件路径；空 = 禁用文件导出	（空）
ONEPATH_TRACE_SERVICE_NAME	资源属性 service.name，标识当前服务	"onepath"
ONEPATH_TRACE_AUTO_INJECT	自动注入开关；0 = 仅透传用户附件，不自动注入追踪上下文	1
ONEPATH_TRACE_FLUSH_MS	NDJSON 异步刷盘间隔（毫秒）	500

指标（Metrics）

变量	作用	默认值
ONEPATH_METRICS_ENABLE	指标总开关；设为 1 启用，未启用时指标注册返回空、后续调用 no-op、零开销	0
ONEPATH_METRICS_NDJSON_PATH	指标快照 NDJSON 导出路径；空 = 禁用文件导出	（空）
ONEPATH_METRICS_FLUSH_MS	指标 NDJSON 异步刷盘间隔（毫秒）	1000

使用示例

无需改一行代码，运行前用环境变量开启即可：

ONEPATH_TRACE_ENABLE=1 \
ONEPATH_TRACE_SAMPLE_RATIO=1.0 \
ONEPATH_TRACE_NDJSON_PATH=/tmp/trace.ndjson \
ONEPATH_TRACE_SERVICE_NAME=my-app \
ONEPATH_METRICS_ENABLE=1 \
ONEPATH_METRICS_NDJSON_PATH=/tmp/metrics.ndjson \
./your_app

行为要点

• 读取时机：所有变量在追踪 / 指标子系统首次初始化时读取一次并缓存。若应用未显式初始化，首次发布 / 订阅 / 查询会触发惰性初始化（此时读取环境变量），从而保证「不改代码即可启用」。之后再修改环境变量无效。
• 零开销保证：*_ENABLE=0 时，相关 API 全部退化为 no-op，吞吐与禁用时持平。TRACE_ENABLE=1 + SAMPLE_RATIO=0.0 仅维护调用栈、不导出，吞吐下降 < 5%；全采样 + NDJSON 导出含文件 I/O，吞吐下降 < 30%。
• 跨节点端到端延迟：端到端延迟指标依赖系统实时钟。跨节点部署务必同步时钟（NTP / PTP），否则负延迟样本会被丢弃。

完整的追踪上下文传播、自动埋点覆盖范围、多跳透传与指标对接，详见 专有场景 · 链路追踪。