Skip to main content

网络监控使用指引

一句话了解

网络监控（HTTP 监控）采集 App 内 HTTP 请求的耗时、成功率、传输数据量，并细分到 DNS、TCP、TLS 等关键阶段，帮助你发现并定位网络质量问题。

支持平台与版本：Android（SDK 4.4.8.2 及以上，推荐新接入方式）、iOS（SDK 2.8.0-beta 及以上）。4.4.8.2 以下的 Android 版本见 FAQ。

灰度说明

Android 网络监控功能仍在灰度验证中，建议先小范围灰度试用，质量验证符合预期后再正式全量上线。

一、功能简介​

1. 监控什么​

  • 请求耗时：整体耗时，以及 DNS、TCP 连接、TLS 握手、发送、等待、接收等阶段的耗时。
  • 成功率：以错误率衡量，可下钻到错误类型、错误码、异常信息。
  • 传输数据量：单次请求的请求 / 响应体大小。
  • 多维下钻：可按域名、接口（URL）、APP 版本等多种字段聚合和下钻分析。

请求耗时各阶段的含义如下（以 OkHttp 事件为例）：

请求阶段耗时

指标含义
请求耗时从请求开始（callStart）到请求结束（callEnd / callFailed）的总耗时
DNS 时间域名解析耗时
TCP 时间TCP 连接建立耗时
SSL / TLS 时间TLS 握手耗时，包含在 TCP 连接阶段内
首包时间 / 网络延时从请求开始到收到响应头的耗时，包含发送时间与等待时间
发送时间发送请求的耗时
等待时间请求发送完成后，等待服务端响应的耗时
接收时间从收到响应头到接收完响应体的耗时

2. 覆盖范围​

平台覆盖的请求不覆盖的请求
Android基于 OkHttp3 的 HTTP / HTTPS 请求（含 Retrofit 等基于 OkHttp 的网络库）；系统原生 URLConnection 请求（插桩方案自动覆盖；主动适配方案需按下文接入）既非 OkHttp3、也非系统原生接口实现的请求；使用 OkHttp3 但未经 Bugly 适配创建的 OkHttpClient
iOS使用 NSURLSession 发起的 HTTP 请求通过 NSURLConnection、CFNetwork 或基于 Socket 的连接发起的请求

二、接入流程​

步骤内容位置
1SDK 接入：Android 与 iOS 方式不同客户端
2SDK 配置：在管理台开启 net_quality 并设置采样率管理台
3验证接入：确认配置生效、数据已采集并上报客户端日志
4查看数据管理台
客户端与管理台共同控制

网络监控需要客户端接入完成，并且管理台配置开启（采样率大于 0）后才会真正生效。

三、SDK 接入​

1. Android​

前提：SDK 4.4.8.2 及以上，并已完成 Bugly 初始化（见 Android SDK 接入）。

implementation "com.tencent.bugly:bugly-pro:4.4.8.2"

自 4.4.8.2 起，接入接口升级为 ClientBuilder 体系，提供两种接入方式，二选一：

方式说明
方案一：代码自动插桩（推荐）引入 Bugly 的 Gradle 插件，编译期自动插桩，无需修改网络请求代码，自动覆盖 OkHttp 与系统原生 URLConnection
方案二：业务主动适配在业务代码中调用 Bugly 提供的适配接口，覆盖 OkHttp 与系统原生 URLConnection

方案一：代码自动插桩（推荐）​

第一步：在项目根目录 build.gradle 的 buildscript 节点，补充 BuglyPerf 插件信息。

buildscript {
    repositories {
        google()
        jcenter()
        maven { url 'https://repo1.maven.org/maven2/' }
        maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
        maven { url 'https://mirrors.tencent.com/repository/maven/thirdparty-snapshots' }
    }

    dependencies {
        classpath 'com.android.tools.build:gradle:7.4.2'
        classpath 'com.tencent.bugly.perf:bugly-perf-plugin:1.0.1-SNAPSHOT'
    }
}
插件版本说明

bugly-perf-plugin 当前仍为 SNAPSHOT 版本（1.0.1-SNAPSHOT），需要依赖上方配置的 snapshot 仓库才能拉取，正式版本发布后将更新本文。

第二步：在需要网络监控的子项目 build.gradle 中，引入插件并依赖 Bugly SDK。

plugins {
    // ...
    id 'com.tencent.bugly.perf'
}

// BuglyPerf 代码插桩插件配置
BuglyPerfPlugin {
    debugMode false
    instrumentSomeJar true
    includePackages = ['okhttp3/']
    excludePackages = ['android/support', 'androidx']
    includeJarNames = ['bugly-pro', 'okhttp']
}

// 依赖 Bugly SDK（要求 4.4.8.2 及以上版本）
dependencies {
    implementation "com.tencent.bugly:bugly-pro:4.4.8.2"
}

BuglyPerfPlugin 用于控制哪些代码会被插桩：

配置项说明示例中的取值
debugMode是否为 debug 模式。开启后插桩过程会打印更多日志，便于排查问题；正式构建建议关闭false：不打印额外日志
instrumentSomeJar是否只对指定的 jar 插桩。设为 true 时，仅处理 includeJarNames 中指定的 jartrue：只对指定 jar 插桩
includeJarNames需要插桩的 jar 名称列表['bugly-pro', 'okhttp']：对 Bugly SDK 与 OkHttp 这两个 jar 插桩
includePackages需要插桩的包名（路径）列表['okhttp3/']：只对 okhttp3 包下的类插桩
excludePackages不需要插桩的包名（路径）列表，用于缩小插桩范围['android/support', 'androidx']：跳过 Android 支持库

结合示例，上述配置的含义是：只对 bugly-pro 与 okhttp 两个 jar 进行插桩，且在这些 jar 中只处理 okhttp3/ 包下的类，同时跳过 android/support 与 androidx 包，把插桩范围控制在网络监控所需的最小范围内。

第三步：重新编译构建应用。

./gradlew installDebug

方案二：业务主动适配​

1. OkHttp 请求适配

核心逻辑是：使用经过 Bugly 适配的 OkHttpClient.Builder 来创建 OkHttpClient，这样 Bugly 可以在 Builder 中插入 Interceptor 与 EventListener.Factory。ClientBuilder 的类路径为 com.tencent.bugly.network.ClientBuilder，有两种写法：

// 写法一：ClientBuilder.createClient
OkHttpClient client = ClientBuilder.createClient(oldClient);

// 写法二：ClientBuilder.enhanceBuilder
ClientBuilder.enhanceBuilder(oldBuilder);
OkHttpClient client = oldBuilder.build();

2. 原生 URLConnection 请求适配

如果业务直接使用 Android 系统的原生 URLConnection 发起请求，有两种方案：

  • 全局代理（推荐）：基于 OkHttp 的能力代理系统原生的 HttpURLConnection，只需在进程创建后执行一次开启逻辑，比较简洁。推荐在 Application#onCreate 时尽早开启。
// 开启代理
BuglyURLStreamHandlerFactory.init();

// 关闭代理：开启后也可以动态关闭
BuglyURLStreamHandlerFactory.reset();
  • 逐处包装：通过 ClientBuilder.wrapURLConnection 包装系统返回的 URLConnection。需要修改每一处使用 URL.openConnection 的地方，比较繁琐。
HttpURLConnection connection = ClientBuilder.wrapURLConnection(url.openConnection());
采集过滤与 Hook 范围

在 Bugly 初始化后，可通过 NetQualityUserConfig（com.tencent.bugly.network.NetQualityUserConfig）配置离线采集、本地地址 / 指定域名过滤、URLConnection Hook 等行为，参数说明见 全链路追踪 FAQ。

2. iOS​

前提：SDK 2.8.0-beta 及以上。

网络监控属于 Bugly SDK 的子模块，无需编写专门的接入代码，只需在初始化 SDK 时，确保启用的模块中包含 BUGLY_MODUEL_NETWORK，或直接使用 RM_MODULE_ALL：

// 启用网络监控模块（按需追加其他模块）
NSArray *modules = @[BUGLY_MODUEL_NETWORK];
// 或启用所有模块
// NSArray *modules = RM_MODULE_ALL;
[Bugly start:modules config:config completeHandler:^{
    // SDK 初始化完成后的回调
}];
说明
  • BUGLY_MODUEL_NETWORK 即 SDK 中该常量的实际拼写。
  • iOS 仅监控使用 NSURLSession 发起的 HTTP 请求。
  • 系统版本限制：自 2.7.55.1 版本起，网络监控仅支持 iOS 13.0 及以上系统。

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

四、SDK 配置​

1. 开启配置​

网络监控默认关闭，需要在管理台开启：进入 设置 / SDK配置 / 功能配置，添加 net_quality 配置项，并调整采样率及其他参数。

添加网络监控配置项

网络监控配置示例

2. 配置项说明​

配置项适用平台含义
sample_ratioAndroid、iOS设备采样率，取值 [0, 1]，表示允许多少比例的设备开启网络监控
daily_report_limitAndroid每天最多允许上报次数
max_batch_countAndroid一条上报中最多包含多少条 HTTP 明细，默认 100
min_batch_countAndroid一条上报中最少包含多少条 HTTP 明细，默认 50

批量上报机制（Android）：网络监控采集到的每个 HTTP 请求是一条样本，样本会先在本地聚合，满足 min_batch_count ≤ 批量大小 ≤ max_batch_count 后合并为一条上报。

批量上报

iOS 差异

iOS 端没有复杂的上报频率控制，不需要配置 daily_report_limit、max_batch_count、min_batch_count。同时受数据量限制，不建议把 iOS 的采样率调得过高。

接入验证阶段建议
  1. 把 sample_ratio 设为 1（全采样），验证结束后再按实际情况下调。
  2. 把 min_batch_count 调小（如 5 或 10），让数据尽快上报到后台，验证结束后还原默认值或按业务调整。
  3. 把 daily_report_limit 设为 10000，避免验证期间达到每日上报上限而收不到数据。

SDK 配置任务的创建、过滤条件、优先级等通用机制见 SDK 配置使用指引。

五、验证接入​

Android​

按顺序检查以下日志（均可通过日志 TAG 过滤）：

1. 配置已拉取并允许开启：TAG 为 RMonitor_config，包含 dump for loadConfig 的日志中，net_quality:true 表示允许开启，net_quality:false 表示被禁止。

I  dump for loadConfig, {..., net_quality:true, ...}

2. 功能已开启：TAG 为 RMonitor_net_quality，出现 startCollector 表示已开启。

D  startCollector
I  start

3. 数据已采集：TAG 为 RMonitor_net_quality，出现 onCallFinished 表示已成功采集到请求数据。

V  onCallFinished, data: {url: https://xxx/xxx, host: xxx, statusCode: 200, cost: 119}

4. 数据已上报：应用退后台后，如果样本量满足最低上报要求，会出现以下日志。

D  try report or cache data for background.
V  reportNow, plugin: net_quality, strategy: ReportStrategy(...)

iOS​

开启成功后，会出现以下日志：

[Bugly][Event][BuglyNetworkMonitor.mm:281]BUGLY_MODUEL_NETWORK start network monitor: 1048576, 1048576, 1048576

六、管理台使用​

Android 与 iOS 的网络监控数据在管理台中的展示完全一致。

1. 功能入口​

登录管理台，在左侧导航的 网络 下可查看网络监控数据，包含两个模块：

  • HTTP：所有被监控 HTTP 请求的质量数据
  • 网络错误：所有 HTTP 请求错误的数据

网络监控入口

2. HTTP​

展示所有被监控 HTTP 请求的质量数据，默认展示最近 7 天，包含按上报量排序的 Top 域名和接口、整体趋势、统计分布，以及按 URL 聚合的列表。

HTTP 概览

  • 趋势分析：包含成功率、请求耗时、各阶段耗时、传输数据量等丰富指标。

    趋势分析

  • 统计分布：支持针对丰富的字段分析上报占比。

    统计分布

    统计分布

  • URL 列表：按域名 + 接口聚合。

    URL 列表

  • 多维下钻：点击期望分析的域名或接口，可在右侧查看该域名 / 接口的独立数据。

    多维下钻

3. 网络错误​

包含所有 HTTP 请求错误的数据，通过错误率衡量请求成功率。

网络错误概览

  • 趋势分析

    错误趋势

  • 错误列表：按 HTTP 方法 + 域名 + 接口 + 错误码聚类。

    错误列表

  • 错误分布：与 HTTP 一致，提供丰富的下钻字段，便于分析各维度的上报占比。

    错误分布

错误数据中的结果码、HTTP 状态码、异常信息、异常类型的含义见 FAQ。

4. URL 详情与链路追踪​

从 URL 列表或错误列表点击某一接口，可进入 URL 详情 页，查看该接口的详情分析与下钻分析，以及具体请求的明细与错误详情。

在错误详情中点击 链路追踪 ID，可查看该次请求对应的服务端调用链，详见 全链路追踪使用指引。

URL 详情

七、FAQ​

为什么配置了网络监控，却看不到数据？​

按以下顺序排查：

  1. SDK 版本是否满足要求：Android 推荐 4.4.8.2 及以上，iOS 需 2.8.0-beta 及以上。
  2. 客户端是否接入正确：Android 确认插桩插件或适配接口已生效；iOS 确认初始化的模块包含 BUGLY_MODUEL_NETWORK。
  3. 管理台是否开启配置：已添加 net_quality，且 sample_ratio 大于 0。
  4. 设备是否命中采样：sample_ratio 较低时，只有部分设备会开启监控，验证阶段建议设为 1。
  5. 是否满足上报条件（Android）：样本会先本地聚合，应用退后台时才检查样本量是否达到 min_batch_count，满足则上报，否则等下次切后台再检查。验证阶段可把 min_batch_count 调小。
  6. 是否触达每日上限（Android）：检查 daily_report_limit。
  7. 请求是否在覆盖范围内：参见 覆盖范围。
  8. 对照 验证接入 中的日志，确认卡在哪一步。

错误数据中的结果码、HTTP 状态码、异常信息、异常类型分别是什么？​

字段含义
结果码描述 HTTP 连接建立阶段的错误。Android 只有 0 与 -1：0 为默认值，-1 表示连接建立阶段发生了异常，具体原因由异常信息描述
HTTP 状态码服务端对请求的处理结果（三位数字），如 200 请求成功、301 永久重定向、400 客户端请求错误、404 资源未找到、500 服务端内部错误
异常信息异常的具体原因，如域名解析异常 Unable to resolve host "www.xxx.com": No address associated with hostname
异常类型对异常信息的分类，如上例提取的异常类型为 Unable to resolve host

Android 4.4.8.2 以下版本如何接入？​

建议升级

4.4.8.2 以下版本使用 BuglyListenerFactory 方式接入，新版本推荐升级后使用上文的 ClientBuilder 方式。

当前支持（无插桩方案）：

  1. 按下文接入，使用 BuglyListenerFactory 创建的 OkHttpClient，可监控 HTTP / HTTPS 请求的质量。
  2. 通过 BuglyURLStreamHandlerFactory 代理系统原生的 HttpURLConnection，可监控使用系统原生接口实现的 HTTP / HTTPS 请求。

当前不支持：

  1. 既不是系统原生接口、也不是 OkHttp3 实现的 HTTP 请求。
  2. 组件使用了 OkHttp3，但没有调整 OkHttpClient 的创建过程，即没有使用 BuglyListenerFactory 作为 EventListener.Factory。

SDK 版本：需要 4.4.2.5 及以上。

implementation "com.tencent.bugly:bugly-pro:4.4.2.5"

1. 代理系统原生的 HttpURLConnection（如无需监控原生接口请求，可跳过）：推荐在 Application#onCreate 时尽早开启。

BuglyURLStreamHandlerFactory.init();   // 开启代理
BuglyURLStreamHandlerFactory.reset();  // 关闭代理

2. 修改 OkHttpClient 创建过程：创建 OkHttpClient 时使用 BuglyListenerFactory。

OkHttpClient client = new OkHttpClient.Builder()
        .eventListenerFactory(BuglyListenerFactory.getInstance())
        .build();

3. 异步请求使用 BuglyCallbackProxy 封装 Callback：

call.enqueue(new BuglyCallbackProxy(callback));

4. 业务自己也有 EventListener.Factory 时，通过以下代码添加或移除：

BuglyListenerFactory.getInstance().addFactory(myFactory);
BuglyListenerFactory.getInstance().removeFactory(myFactory);

5. 构建测试数据：可参考以下示例构造请求，用于验证接入。

// 异步请求
OkHttpClient client = new OkHttpClient.Builder()
        .eventListenerFactory(BuglyListenerFactory.getInstance())
        .build();

Request request = new Request.Builder().url(url).build();
Call call = client.newCall(request);
call.enqueue(new BuglyCallbackProxy(callback));
// 同步请求
OkHttpClient client = new OkHttpClient.Builder()
        .eventListenerFactory(BuglyListenerFactory.getInstance())
        .build();

Request request = new Request.Builder().url(url).build();
Call call = client.newCall(request);

try (Response response = call.execute()) {
    if (response.isSuccessful()) {
        InputStream inputStream = response.body().byteStream();
        // ...
    }
} catch (IOException exception) {
    //
}

Android 4.4.8.2 以下版本如何验证接入？​

旧版的验证日志如下，按顺序检查：

1. 检查配置拉取，确认网络监控允许开启：日志 TAG 为 RMonitor_config，包含 dump for onConfigLoad。出现 net_quality:true 表示允许开启，net_quality:false 表示不允许开启。

I/RMonitor_config: dump for onConfigLoad, {battery_metric:false, memory_quantile:true, io:false, list_metric:false, work_thread_lag:false, sub_memory_quantile:false, fd_leak:false, looper_metric:true, activity_leak:true, battery_element:false, battery:false, launch_metric:true, battery_ele_metric:false, looper_stack:true, java_memory_ceiling_hprof:false, native_memory:true, http:false, traffic_detail:false, net_quality:true, device:false, db:false, big_bitmap:true, traffic:false}

2. 检查网络监控是否正常开启：

I/RMonitor_net_quality: getFactory, ret: true, factory: null, errorMsg: null
I/RMonitor_net_quality: setURLStreamHandlerFactory success.
I/RMonitor_net_quality: init, true
I/RMonitor_net_quality: start

3. 检查数据上报：

D/RMonitor_report: reportInternal-onSuccess, pluginName: net_quality, dbId: 7

旧版异步请求为什么要用 BuglyCallbackProxy 封装 Callback？​

  1. Bugly SDK 通过 EventListener 监听请求生命周期事件，在 callFailed 和 callEnd 时记录这次 HTTP 请求结束。
  2. 异步请求时，通过 getResponseWithInterceptorChain 拿到 Response 后，即回调业务设置的 Callback。如果业务在 Callback 中，在读取数据流之前就抛出了异常，或没有在 onResponse 中读取数据流，则 EventListener 不会收到 callEnd 或 callFailed 回调。
  3. 使用 BuglyCallbackProxy 封装 Callback 后，可以在 Callback 的 onFailure 和 onResponse 结束后，主动补充一个 callEnd 或 callFailed 回调。
  4. 否则只能依赖网络监控模块的超时检查，来结束这些未能正常收到 callEnd / callFailed 的请求。

BuglyCallbackProxy 原理

旧版如何接入 Retrofit？​

Retrofit 底层依赖 OkHttp 完成实际的 HTTP 通信，只需把配置好的 OkHttpClient 交给 Retrofit：

// 创建 OkHttpClient，配置 EventListener.Factory
OkHttpClient client = new OkHttpClient.Builder()
        .eventListenerFactory(BuglyListenerFactory.getInstance())
        .build();

// Retrofit 使用自定义的 OkHttpClient
Retrofit retrofit = new Retrofit.Builder()
        .baseUrl(url)
        .client(client)
        .addConverterFactory(GsonConverterFactory.create())
        .build();

使用 Retrofit 无需再通过 BuglyCallbackProxy 封装 Callback：Retrofit 封装了 OkHttp 的 enqueue，在回调业务的 onResponse 之前就已经调用 parseResponse 并关闭了数据流，不会出现 EventListener 收不到 callEnd / callFailed 的问题。

4.4.8.2 及以上版本：使用插桩方案无需额外处理；使用主动适配方案时，把 ClientBuilder 适配后的 OkHttpClient 通过 Retrofit.Builder#client 传入即可。

网络监控和流量监控是什么关系？​

两者是独立的功能，在管理台中分别展示，在 SDK 配置中分别开关，互不依赖。流量监控的使用说明请参考 Android 流量监控 与 iOS 流量监控。

如何过滤本地请求或指定域名的请求？​

Android 可通过 NetQualityUserConfig 的 filterLocalhostRequests、filterSomeDomainRequests、filterDomains 参数实现，详见 全链路追踪 FAQ。

相关阅读：

Bugly监控定位
无极智能低码
Hippy开发框架
Shiply容器与发布
Copyright © 1998 - 2024 Tencent. All Rights Reserved.
服务协议
隐私保护声明
腾讯公司版权所有主体备案号粤B2-20090059