Android (Kotlin) 移动应用监控

介绍

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

SDK 监控内容

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

应用崩溃： 实时检测和分析致命及非致命崩溃，附带详细诊断信息。
ANR（应用无响应）事件： 识别影响用户体验的 UI 冻结和主线程阻塞。
网络请求性能： 跟踪不同网络条件下 API 响应时间、失败和延迟。
自定义事务和日志： 捕获关键业务事件，支持深入排查。
用户会话洞察： 理解真实用户如何使用您的应用，并在会话级别隔离问题。

SDK 带来的能力

集成后，SDK 可帮助您：

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

前提条件

要求	最低要求
Android SDK (compileSdk)	API 21（Lollipop）或更高版本
Kotlin（如适用）	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 （或 build.gradle.kts）文件中。

Groovy（build.gradle）

dependencies {
    implementation "com.manageengine.apminsight:mobileapm:3.0.0"
}

Kotlin DSL（build.gradle.kts）

dependencies {
    implementation("com.manageengine.apminsight:mobileapm:3.0.0")
}

在 settings.gradle 文件中包含仓库 URL。

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

所需权限： 确认以下权限已添加至 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 配置与集成

1. 初始化 SDK

/**
* Initializes the ME APM Insight agent.
 * @param context The application context.
 */
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        MEAPMInsight.initMonitoring( context = this )
   }
}

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

2. 启用崩溃报告

ManageEngine APM Insight SDK 会自动捕获所有未捕获异常。每个崩溃报告包含发生时间戳和完整堆栈跟踪，便于根因分析。

MEAPMInsight.enableErrorReporting()

3. 启用 ANR 监控

检测主线程长时间阻塞导致的应用无响应（ANR）事件，防止 Android 弹出“应用无响应”对话框。须在 initMonitoring()

// 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()
}

后使用以下 API 启用 ANR 监控。

4. 启用碎片跟踪

MEAPMInsight.enableFragmentSupport()

选项 1：全局启用

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

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    supportFragmentManager.registerFragmentLifecycleCallbacks(
        MEAPMInsightFragmentLifecycleCallbacks(),
        true
    )
}

若只想在特定活动中启用碎片跟踪，请在这些活动内手动注册生命周期回调：

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)

val client = OkHttpClient.Builder()
 .addNetworkInterceptor(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 默认自动捕获所有屏幕（Activities）。若某屏幕未被自动检测，可用以下 API 手动跟踪：

业务级监控

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

1. 事务

事务的特点： 线程安全：
可跨线程启动和停止。 单次使用：
每个事务实例仅能启动和停止一次。 按名称聚合：

同名事务会分组统计。

对多次同名操作，SDK 会记录平均执行时间。请使用清晰、一致的名称准确跟踪业务操作。



val transaction = Apm.startTransaction("List Articles")

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

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

// Download articles
transaction.stopComponent(articlesComponent)

for (article in articles) {
    val thumbnailComponent = transaction.startComponent("Download Thumbnail")
    
    // Download thumbnail
    
    transaction.stopComponent(thumbnailComponent)
}

// Stop HTTP component
transaction.stopComponent(httpComponent)

// Stop transaction
Apm.stopTransaction(transaction)

高级控制

1. 刷新数据

使用下列 API 立即上传已记录的遥测数据，避免等待默认的 60 秒上传周期。

MEAPMInsight.flush()

2. 排除 HTTP 调用

传入指定 URL 列表，排除这些请求的跟踪。

MEAPMInsightexcludeHttpCalls(listOf("example.com", "test.com"))

3. 排除屏幕

传入指定屏幕名称列表，排除这些屏幕的跟踪。

MEAPMInsight.excludeScreens(listOf("customScreenName"))

4. 停止监控

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

MEAPMInsight.stopMonitoring()

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

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

MEAPMInsight.addSensitiveParams(listOf("x-custom-token", "account_id", "ssn"))

6. ProGuard / R8 规则

若使用代码混淆，请将以下规则添加至 proguard-rules.pro 文件：

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