Android 移动应用监控（Java）

介绍

ManageEngine Mobile APM Insight SDK for Android 帮助您监控原生 Android 应用在真实用户设备上的性能和稳定性。它提供可操作的应用行为洞察，并支持与 Java 和 Kotlin 应用的无缝集成。

SDK 监控内容

深入了解您的应用健康状况和性能：

应用崩溃： 立即检测并分析致命和非致命崩溃，附带详细诊断信息。
ANR（应用无响应）事件： 识别影响用户体验的 UI 卡顿和主线程阻塞。
网络请求性能： 跟踪不同网络条件下的 API 响应时间、失败和延迟。
自定义事务和日志： 捕获关键业务事件以便深入排查。
用户会话洞察： 了解真实用户的应用交互行为，并在会话级别定位问题。

使用 SDK 可实现的目标

集成后，SDK 使您能够：

跟踪业务事务： 测量关键流程（如登录、结算或新用户引导）的性能。
自动监控 HTTP 调用： 在影响用户之前检测慢速 API 和后端瓶颈。
实时捕获崩溃： 主动识别稳定性问题并更快解决。
跟踪屏幕和 Fragment： 了解屏幕加载时间和用户导航模式。
标记并跟踪特定用户： 无需猜测，调试单个用户问题。
区分环境： 独立监控生产、预发布、QA 和开发版本。
排除特定调用或屏幕： 仅关注重要数据，过滤非关键遥测。
手动刷新遥测数据： 确保在需要时立即传输性能数据。

前提条件

需求	最低要求
Android SDK（compileSdk）	API 21（Lollipop）或更高版本
Java	1.8+
AndroidX	必须启用（gradle.properties 中 android.useAndroidX=true）
ManageEngine Applications Manager -	一个带有效 AppKey 的活动监控器

入门

在将 ManageEngine APM Insight Android SDK 添加到您的 Android 应用之前，您需要创建一个移动应用监控器，并从 Applications Manager web 下载配置（apm_config.json）文件。

在 res 目录下创建一个名为 raw 的 Android 资源目录（如果不存在）： app/src/main/res/raw/
将下载的配置文件放入 res 文件夹，且不要重命名或修改其内容： app/src/main/res/raw/apm_config.json
添加自签名服务器证书（不推荐生产环境使用）： 如果您的 DEM Collector 使用自签名（默认捆绑）SSL 证书，必须将该证书添加到 Android 项目以建立安全连接。操作步骤是将 apm_cert.cer 文件从 DEM Collector 安装目录（/conf/sslcerts）复制到相同 res 目录： app/src/main/res/raw/apm_cert.cer
将 Mobile APM SDK 添加到您的应用级别 build.gradle 文件中。
Groovy（build.gradle）
```
dependencies {
        implementation "com.manageengine.apminsight:mobileapm:3.0.0"
}
```

在 settings.gradle 文件中。

dependencyResolutionManagement {
    repositories {
    google()
    mavenCentral()
    maven {
        url = uri("https://maven.zohodl.com/")
        content {
            includeGroup("com.manageengine.apminsight")
        }
    }
}
}

中包含仓库 URL。 必需权限： 确保以下权限已添加到 AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

文件中：

SDK 配置与埋点

/**
 * Initializes the ME APM Insight  agent.
 * @param context The application context.
 */

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        MEAPMInsight.initMonitoring( this );
    }
}

1. SDK 初始化 注意：

如果 SDK 在应用启动后初始化，请传入活动 Activity 实例作为上下文，确保立即开始屏幕和生命周期监控。

2. 启用崩溃报告 ManageEngine APM Insight SDK 会自动捕获所有未捕获异常

MEAPMInsight.enableErrorReporting();

。每个崩溃报告包含发生时间戳和完整堆栈跟踪，便于根因分析。

3. 启用 ANR 监控

// Default timeout (5 seconds)
MEAPMInsight.startANRWatching();
// Custom timeout// Report ANR if the main thread is blocked for more than 3 seconds
MEAPMInsight.startANRWatching(3000);
//Stop ANR Monitoring
MEAPMInsight.stopANRWatching();
}

检测应用无响应（ANR）事件，即主线程（UI 线程）长时间阻塞，导致 Android 弹出“应用无响应”对话框。必须使用以下 API 启用 ANR 监控：

4. 启用 Fragment 跟踪

MEAPMInsight.enableFragmentSupport();

选项 1：全局启用

选项 2：仅针对特定活动启用

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    this.getSupportFragmentManager();
        .registerFragmentLifecycleCallbacks(
            new MEAPMInsightFragmentLifecycleCallbacks(),
            true
        );
}

若仅需为某些活动启用 Fragment 跟踪，则在这些活动内手动注册生命周期回调：

5. 设置环境

/**
   *@param {String} environment
        Custom environment types like debug, release, or beta release.
   */
MEAPMInsight.setEnvironment("release");

可使用以下 API 设置自定义环境信息，以便在开发、调试、生产或发布等不同环境中筛选数据。

6. 设置自定义用户 ID

将遥测数据与特定用户关联。SDK 会在存储或传输前自动对用户 ID 进行哈希处理（SHA-256）。默认情况下，SDK 会生成唯一用户 ID。若需自定义用户 ID，可通过以下语法实现。此功能适用于跟踪特定用户的指标或调试问题。重要提示：

/**
   *@param {String} userId
   */
MEAPMInsight.setUserId("user_12345");

请勿传递原始的个人可识别信息（PII），如电子邮件地址、电话号码或真实姓名。请使用内部用户 ID 或 UUID 等不透明标识符。

7. HTTP 调用跟踪

java.net.HttpURLConnection
javax.net.ssl.HttpsURLConnection

OkHttp (when the SDK interceptor is added)

OkHttpClient client = new OkHttpClient.Builder()
        .addNetworkInterceptor(new MEAPMInsightInterceptor())
 .build();

SDK 默认自动监控通过以下库发出的网络请求，无需额外配置：

/**
 * @param {String} url
 * The complete request URL.
 *
 * @param {String} requestMethod
 * The HTTP method used (e.g., GET, POST, PUT, DELETE).
 *
 * @param {long} startTime
 * The request start time in milliseconds.
 * You can obtain this using System.currentTimeMillis().
 *
 * @param {long} loadTime
 * The total time taken to complete the request, measured in milliseconds.
 *
 * @param {int} responseCode
 * The HTTP response status code returned by the server.
 *
 * @param {String} screen
 * The name of the screen from which the HTTP call was initiated.
 */

Apm.addHttpCalls(
"https://www.example.com",
"GET",
System.currentTimeMillis(),
526,
200,
"PaymentScreen"
);

如果应用使用自定义网络层或未自动监控的库，可使用以下 API 手动跟踪 HTTP 调用：

8. 屏幕跟踪

/**
   *@param {String} screenName
   *@param {String} orientation
   *@param {long} loadTime measured in millis
   *@param {long} startTime measured in millis
   */
Apm.addScreen("DetailScreen", "portrait", 50, 1642743078700);

SDK 默认自动捕获所有屏幕（Activity）。若某个屏幕未被自动检测，可使用以下 API 手动跟踪：

业务级监控

Start a transaction using Apm.startTransaction("Transaction_Name") before a long-running operation and call stop() when it completes.

1. 事务

事务具备以下特性： 线程安全：
可跨线程启动和停止。 单次使用：
每个事务实例仅能启动和停止一次。 按名称平均：

同名事务被归为一组。

当同一操作多次使用相同事务名称执行时，SDK 会记录这些执行的平均耗时。

/**
 * Transaction
 *
 * @param {String} transactionName
 * A meaningful name representing the overall business operation.
 *
 * Component
 *
 * @param {String} componentName
 * A descriptive name for the sub-operation being measured.
 *
 * @param {int} componentType
 * Predefined component type (e.g., Component.TYPE_HTTP).

 */

Transaction transaction = Apm.startTransaction("List Articles");

// Start predefined HTTP component
Component httpComponent = transaction.startComponent(Component.TYPE_HTTP);

// Start custom component
Component articlesComponent = transaction.startComponent("Download Articles");

// Download articles
transaction.stopComponent(articlesComponent);

for (Article article : articles) {
    Component thumbnailComponent =
            transaction.startComponent("Download Thumbnail");
    // Download thumbnail
    transaction.stopComponent(thumbnailComponent);
}
// Stop HTTP component
transaction.stopComponent(httpComponent);

// Stop transaction
Apm.stopTransaction(transaction);

使用清晰、一致的名称以准确追踪业务操作。

高级控制

1. 刷新数据

MEAPMInsight.flush();

使用以下 API 立即上传已记录的遥测数据至服务器，而非等待下一个上传周期。默认上传间隔为 60 秒。

2. 排除 HTTP 调用

/**
@param {Lis<String>} listOfUrls
*/

MEAPMInsight.excludeHttpCalls(Arrays.asList("example.com"));

可通过向以下 API 传递 URL 列表排除特定 URL 的跟踪。

3. 排除屏幕

/* 
 *  param 
 * List<String> listOfScreens
 */
MEAPMInsight.excludeScreens(Arrays.asList("customScreenName"));

可通过向以下 API 传递屏幕名称列表排除特定屏幕的跟踪。

4. 停止监控

MEAPMInsight.stopMonitoring();

使用以下 API 停止所有数据采集（屏幕、HTTP 调用、事务、崩溃、ANR 检测）。

5. 隐藏敏感数据

SDK 会自动隐藏已知敏感查询参数和请求头的值，发送数据前替换为 *****。以下关键字将自动被隐藏：
apikey, api_key, apitoken, api_token
authorization, auth, token, access_token, refresh_token, auth_token, secret, client_secret
username, user, email, password, passwd, pass

sessionid, session_id, session_token

List<String> customSensitiveKeys = Arrays.asList("x-custom-token", "account_id", "ssn");
MEAPMInsight.addSensitiveParams(customSensitiveKeys);

若需添加自定义敏感关键字，请使用以下 API：

6. ProGuard / R8 规则 若启用代码混淆，请将以下规则添加至 AndroidManifest.xml

-keep class manageengine.mobileapm.android.apm.** { *; }
-dontwarn manageengine.mobileapm.android.apm.**