全链路追踪使用指引

一句话了解

Bugly 全链路追踪把链路的起点从后台延伸到用户设备：SDK 在 App 发出的 HTTP 请求头中自动注入标准追踪标识，后台 APM 据此串起完整调用链，Bugly 再把端上请求与服务端链路关联，在管理台一键查看。

支持平台与版本：Android（SDK 4.4.8.2 及以上）、iOS（SDK 2.8.3-beta.2 及以上）。

一、功能简介

1. 什么是全链路追踪

全链路追踪（Full-Link Tracing）用于监控和分析分布式系统中一次请求从发起到响应的完整路径。它就像给每次请求分配一个「全程物流单号」，无论请求在系统内部经过多少个服务「中转站」，都能清晰看到整个行程和每个环节的状态。

2. Bugly 全链路追踪的特色

传统链路追踪的起点是到达网关或首个后端服务的请求，看不到请求在用户设备上的那一段。Bugly 在此基础上做了三点扩展：

特色	说明
起点前移，端到端覆盖	基于网络监控能力，在客户端拦截所有发出的 HTTP 请求并自动注入追踪标识，让链路覆盖「客户端 → 网络 → 后台服务」的完整过程
遵循开放标准，无缝对接	注入的 traceparent 遵循 W3C Trace Context 规范，sw8 兼容 Apache SkyWalking 协议。只要后台追踪系统（如 Zipkin、Jaeger、SkyWalking、腾讯云 APM）能解析这些标准，就能继续传递并还原链路
关联多维数据，精准定位	将客户端请求与后台链路关联，快速判断问题出在客户端网络、特定机型，还是后台服务；也可将后台耗时与页面加载、应用启动等端上指标关联分析

二、实现原理

1. 注入标识：App 发起 HTTP 请求时，Bugly SDK 在请求头中注入 TraceID 等追踪标识。
2. 透传标识：请求到达后台，接入了 APM 的服务识别请求头，沿用同一个 TraceID 生成自己的 Span，并继续传给下游服务。
3. 汇聚链路：各服务把 Span 上报到腾讯云 APM，APM 按 TraceID 还原出完整调用链。
4. 两端关联：SDK 同时把请求质量数据（含 TraceID）上报到 Bugly。在管理台点击 链路追踪 ID，Bugly 即通过已绑定的 APM 账号查询并展示对应的服务端链路。

核心概念

概念	说明
Trace（链路）	一次完整请求的调用过程，由全局唯一的 TraceID 标识
Span（跨度）	链路中的一个执行单元，记录操作的开始时间、耗时、标签（HTTP 方法、URL、状态码）和异常
TraceID	整条链路共用，在所有服务间透传
SpanID / ParentSpanID	每个 Span 的唯一标识及其父节点标识，Span 之间通过父子关系组成一棵「调用树」

关联的前提

两端能对上同一条链路，需要同时满足：客户端已注入追踪标识，且服务端已接入 APM 并识别、透传该标识。任一环节缺失，Bugly 中就无法展示对应的服务端链路。

三、接入流程

步骤	内容	位置
1	接入网络监控（全链路追踪基于网络监控采集请求）	客户端 + 管理台
2	打开全链路追踪配置	客户端
3	服务端接入腾讯云 APM	服务端
4	在 Bugly 中绑定 APM 账号	管理台

平台差异

Android 与 iOS 的客户端接入（步骤 1、2） 不同，请见下一节；步骤 3、4 与平台无关。

四、客户端接入

1. Android

前提：SDK 4.4.8.2 及以上，依赖 com.tencent.bugly:bugly-pro:4.4.8.2。

步骤一：接入网络监控

1. 管理台开启网络监控：网络监控默认关闭，需在 设置 / SDK配置 中调整 net_quality 的采样率来开启。接入验证阶段建议全量打开（sample_ratio 设为 1），把 daily_report_limit 设为 10000，并把 max_batch_count、min_batch_count 调小，方便尽快验证上报；验证完成后恢复默认值或按业务调整。

   

2. 接入 SDK：支持「代码自动插桩」与「业务主动适配」两种方式，二选一，详见 网络监控使用指引 - Android SDK 接入。

步骤二：打开全链路追踪配置

在 Bugly 初始化之后，通过 NetQualityUserConfig 开启追踪标识的注入。NetQualityUserConfig 与 ClientBuilder 都位于 com.tencent.bugly.network 包下。

import com.tencent.bugly.network.ClientBuilder;
import com.tencent.bugly.network.NetQualityUserConfig;

NetQualityUserConfig config = new NetQualityUserConfig();
config.enableAppendTraceParent = true;  // 注入 traceparent（W3C Trace Context）
config.enableAppendTraceState = true;   // 注入 tracestate，需配合 traceparent 使用
config.enableAppendSW8 = true;          // 注入 sw8（SkyWalking）
config.isTraceSample = true;            // 请求是否参与采样
ClientBuilder.setUserConfig(config);

按后台协议选择

根据后台追踪系统支持的协议，开启对应的开关即可：后台使用 W3C Trace Context（如 OpenTelemetry）时开启 traceparent / tracestate；使用 SkyWalking 时开启 sw8。

NetQualityUserConfig 还包含请求过滤、URLConnection 监控等参数，详见 FAQ：NetQualityUserConfig 参数说明。

2. iOS

前提：SDK 2.8.3-beta.2 及以上。Bugly 会 Hook NSURLSession、NSURLConnection 等方法，在请求头中添加追踪字段。

步骤一：管理台开启网络监控与全链路追踪

在 设置 / SDK配置 中添加并开启以下配置项：

配置项	参数	说明
net_quality（网络监控）	sample_ratio	设备采样率，接入验证阶段建议设为 1
full_trace_tracing（全链路追踪）	sample_ratio	设备采样率，接入验证阶段建议调大（图中默认值为 0）
	enable_NSURLRequest	是否允许修改 NSURLRequest，默认 1；设为 0 的场景见 FAQ

步骤二：初始化时启动模块

初始化 SDK 时，同时启动网络监控模块与全链路模块：

// 启动网络模块与全链路模块
NSArray *module = @[BUGLY_MODUEL_NETWORK, BUGLY_MODULE_FULL_TRACE];
[Bugly start:module config:config completeHandler:^{
}];

// 或：启动所有模块
[Bugly start:RM_MODULE_ALL config:config completeHandler:^{
}];

初始化的完整说明见 iOS SDK 接入。

五、服务端接入（腾讯云 APM）

服务端链路数据由腾讯云 APM 承担，需依次完成：创建业务系统 → 接入应用。

用途	地址
APM 控制台	https://console.cloud.tencent.com/monitor/apm/system/list
APM 接入文档	https://cloud.tencent.com/document/product/248/87116

1. 创建业务系统

在 APM 业务系统 页面创建业务系统，并留意两项配置：

• 上报地域：按应用实际部署地域选择。各地域数据互相隔离，业务系统创建后不可更改。
• 链路存储时长：默认 7 天，最长 30 天，超期数据会被丢弃。

2. 接入应用

在 应用列表 中点击 接入应用：

1. 选择接入协议：推荐 OpenTelemetry。
2. 选择上报方式：服务运行在腾讯云 VPC 内时推荐内网上报，更安全且节省上报流量。
3. 获取接入点和 Token：在「接入流程 - 步骤 1」中复制，下一步使用。
4. 按语言接入：参考 APM 接入文档，选择服务端对应的语言，填入接入点和 Token。

接入成功后，APM 应用列表中会出现该应用及其请求量、响应时间、错误数等数据：

六、在 Bugly 中绑定 APM 账号

Bugly 需要通过 APM 账号读取链路数据。在 网络 → URL 详情 的错误详情中点击 链路追踪 ID，首次使用时会弹出「全链路追踪配置」：

配置项	说明
地域（Region）	与创建业务系统时选择的地域一致，如广州 ap-guangzhou
业务系统 ID（InstanceId）	APM 业务系统 ID，形如 apm-xxxx，可在 APM 业务系统 页面获取
SecretId / SecretKey	业务调用腾讯云 API 使用的账号密钥

账号需具备以下接口权限

绑定时 Bugly 会校验账号权限，缺少权限会报错：

• apm:DescribeGeneralOTSpanList
• apm:DescribeSpanTreeByID

不清楚如何申请接口权限时，可联系 APM 小助手。

七、管理台使用

1. 查看某次请求的链路

1. 进入 网络 → URL 详情，选择目标接口与请求。
2. 在右侧 错误详情 中找到 链路追踪 ID。
3. 点击该 ID 右侧的图标，在 Bugly 内打开对应链路（首次使用需先完成上一节的账号绑定）。

2. 查看链路明细

点击后会在右侧弹出「链路追踪」面板，包含「详情」与「配置」两个 Tab：「详情」展示链路明细；「配置」用于修改上一节的 APM 账号配置。

「详情」顶部为链路概要：TraceID、链路状态、总响应时间、应用数、Span 数、开始时间。下方以树形 + 时间轴展示 Span 明细：

• 客户端阶段：「请求总耗时」下拆分出首包时间（DNS、TCP、发送、等待）与接收时间，可判断端上网络哪个阶段慢。
• 服务端调用：按调用层级展开各服务（如 api_server、web_server）的接口调用与下游操作（如 SELECT、POST），不同服务以不同颜色区分，便于定位瓶颈节点与异常节点。

3. 典型排障路径

1. 在 网络 → URL 详情 中，从成功率、错误率或耗时趋势定位到异常的域名 / 接口。
2. 打开一条错误请求，点击 链路追踪 ID 查看链路。
3. 对比端上各阶段耗时与服务端各节点耗时，判断问题出在端上网络、网关，还是下游服务，再定点修复。

八、FAQ

为什么看不到链路，或点击后没有数据？

按以下顺序排查：

1. 客户端是否注入了追踪标识：确认 SDK 版本满足要求，已接入网络监控，且已打开全链路追踪配置（Android 为 NetQualityUserConfig，iOS 为启动 BUGLY_MODULE_FULL_TRACE 模块并在管理台开启 full_trace_tracing）。
2. 设备是否命中采样：net_quality 等配置的 sample_ratio 较低时，只有部分设备会开启监控。
3. 服务端是否接入 APM 并透传标识：服务端须识别请求头中的追踪标识。
4. APM 账号配置是否正确：地域、业务系统 ID 要与 APM 一致，账号需具备 apm:DescribeGeneralOTSpanList、apm:DescribeSpanTreeByID 权限。
5. 是否超过链路存储时长：APM 链路数据默认保存 7 天，最长 30 天。超期后即使 Bugly 上仍有该请求记录，也无法查询到链路。

如何确认请求头已注入追踪字段？

使用抓包工具查看 App 发出的 HTTP 请求，确认请求头中包含 traceparent 或 sw8（取决于你开启的开关）。

traceparent 和 sw8 应该开哪个？

按后台追踪系统支持的协议选择：

• 后台使用 W3C Trace Context（如 OpenTelemetry、Zipkin、Jaeger）：开启 traceparent，需要携带厂商扩展信息时同时开启 tracestate。
• 后台使用 SkyWalking：开启 sw8。
• 也可以同时开启多项。

SDK 注入时，如果请求头中已存在同名字段则不会覆盖。

W3C Trace Context 的 traceparent / tracestate 是什么格式？

W3C Trace Context 是 W3C 制定的标准，通过 HTTP 头部（也可在 gRPC metadata、消息队列属性等位置）传递追踪上下文。

traceparent：携带追踪的核心信息。

// 格式
traceparent: <version>-<trace-id>-<parent-id>-<trace-flags>
// 示例
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

字段	说明
version	2 个字符，版本号，当前为 00
trace-id	32 个字符（16 字节，128 位十六进制），全局唯一的追踪 ID
parent-id	16 个字符（8 字节，64 位十六进制），当前请求的父 Span ID
trace-flags	2 个字符，采样标志，01 表示采样，00 表示未采样

tracestate：可选字段，供应商自定义的追踪信息，用于多供应商链路追踪场景。多个供应商信息用逗号分隔，顺序有意义（最左侧优先）。

tracestate: sw=abc123,ot=xyz456

HTTP 请求示例：

GET /api HTTP/1.1
Host: example.com
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate: sw=abc123

SkyWalking 的 sw8 是什么格式？

SkyWalking 是开源的分布式系统 APM 工具，sw8 是其跨进程传播协议。

// 协议
sw8: <traceId>-<segmentId>-<spanId>-<service>-<serviceInstance>-<endpoint>-<targetAddress>-<sample>
// 示例
sw8: dHJhY2VJZA==-c2VnbWVudElk-MA==-c2VydmljZQ==-aW5zdGFuY2U=-ZW5kcG9pbnQ=-dGFyZ2V0QWRkcmVzcw==-MQ==

字段	说明（均为 Base64 编码）
traceId	位置 1，全局唯一的追踪链路 ID
segmentId	位置 2，当前服务生成的 Segment ID
spanId	位置 3，当前 Span 的编号（整数，通常为 0、1、2...）
service	当前服务名
serviceInstance	当前服务实例名
endpoint	当前调用的入口（如 HTTP 路径）
targetAddress	目标地址（如 主机:端口）
sample	采样标志，"1" 表示采样，"0" 表示不采样

NetQualityUserConfig 有哪些参数？

Android 通过 NetQualityUserConfig 控制网络监控与全链路追踪的行为，需在 Bugly 初始化后通过 ClientBuilder.setUserConfig(config) 设置。

全链路追踪（Trace 注入）

参数	类型	默认值	说明
enableAppendTraceParent	boolean	false	是否在请求头中注入 traceparent。请求头中已存在该字段时不覆盖
enableAppendTraceState	boolean	false	是否在请求头中注入 tracestate。需配合 enableAppendTraceParent 使用
enableAppendSW8	boolean	false	是否在请求头中注入 sw8。请求头中已存在该字段时不覆盖
isTraceSample	boolean	true	Trace 是否采样。true 时 traceparent 与 sw8 的采样标志位置 1；false 时 Trace 头仍会注入，但标记为不采样

数据采集过滤

参数	类型	默认值	说明
enableOfflineMonitoring	boolean	true	无网络（离线）状态下是否仍采集请求数据。设为 false 时，断网期间的请求不会上报
filterLocalhostRequests	boolean	false	是否过滤本地地址请求（127.x.x.x、localhost 等），适合过滤 App 内部 IPC / 代理流量
filterSomeDomainRequests	boolean	false	是否启用域名黑名单过滤。需配合 filterDomains 使用
filterDomains	String[]	null	域名黑名单（精确匹配），仅在 filterSomeDomainRequests = true 时生效，如 new String[]{"bugly.qq.com", "internal.oa.com"}

OkHttp 监控

参数	类型	默认值	说明
enableAutoHookOkhttp	boolean	true	控制插桩入口 ClientBuilder.enhanceBuilder() 是否对 OkHttp 自动 Hook。业务主动调用 ClientBuilder.configBuilder() / ClientBuilder.createClient() 不受此开关控制，始终会注入监控

URLConnection 监控

参数	类型	默认值	说明
enableHookURLConnection	boolean	false	是否对 HttpURLConnection / HttpsURLConnection 进行 Hook，采集通过 URLConnection 发起的请求
enableWrapInputStream	boolean	false	是否包装 URLConnection 的 InputStream（含 ErrorStream），统计响应体接收字节数和耗时。需先开启 enableHookURLConnection
enableWrapOutputStream	boolean	false	是否包装 URLConnection 的 OutputStream，统计请求体发送字节数和耗时。需先开启 enableHookURLConnection

调试

参数	类型	默认值	说明
isDebug	boolean	false	是否为调试 / 验证阶段。true 时优先保证执行效率，放宽多线程可见性约束（该字段未声明 volatile）。仅用于开发测试，生产环境必须设为 false

完整示例（打开所有配置项）：

NetQualityUserConfig config = new NetQualityUserConfig();
config.enableOfflineMonitoring = true;
config.filterLocalhostRequests = true;
config.filterSomeDomainRequests = true;
config.enableAutoHookOkhttp = true;
config.enableHookURLConnection = true;
config.enableWrapInputStream = true;
config.enableWrapOutputStream = true;
config.enableAppendTraceParent = true;
config.enableAppendTraceState = true;
config.enableAppendSW8 = true;
config.isTraceSample = true;
config.isDebug = true; // 推荐 Debug 阶段打开，发布阶段关闭
ClientBuilder.setUserConfig(config);

生产环境最小配置：

NetQualityUserConfig config = new NetQualityUserConfig();
config.filterLocalhostRequests = true;   // 过滤本地流量
config.enableAutoHookOkhttp = true;      // 默认已开启，可不写
ClientBuilder.setUserConfig(config);

支持哪些网络库和请求方式？

• Android：基于 OkHttp 的网络库（如 Retrofit、Fuel、RxEasyHttp）可无缝兼容；系统原生的 URLConnection 也支持，见 网络监控使用指引。
• iOS：Hook NSURLSession、NSURLConnection 等方法，在请求头中添加追踪字段。

iOS 上为什么要设置 enable_NSURLRequest？

iOS 注入追踪字段需要修改 NSURLRequest 的 Header，会把请求对象替换为 NSMutableURLRequest，对象本身会发生变化。如果业务逻辑依赖 NSURLRequest 对象本身做判断（例如根据对象指针值判断），可能受到影响，此时可在管理台 full_trace_tracing 配置中把 enable_NSURLRequest 设为 0。

链路数据保存多久？

由 APM 业务系统的「链路存储时长」决定：默认 7 天，最长 30 天，超过 30 天的数据会被丢弃。

---

相关阅读：

• 端上网络数据来源：网络监控使用指引
• 平台配置机制：SDK 配置使用指引
• 腾讯云 APM：产品文档