alicloud_apm 1.0.0

Alibaba Cloud EMAS APM Flutter plugin providing crash analysis, performance metrics, and native channel integrations for apps.

Alicloud APM For Flutter

阿里云 APM Flutter 插件，提供 Dart 层崩溃分析并桥接 iOS/Android 原生 SDK。
Alibaba Cloud APM Flutter plugin with crash analysis.

特性 Features

• Android/iOS 原生接入，自带原生崩溃监控能力
• 内置 CrashAnalysis：捕获 FlutterError、PlatformDispatcher、Zone、Isolate 及自定义异常
• 支持用户标识、自定义维度、日志级别等配置
• 可调异常策略与堆栈深度，支持自定义异常模型上报

环境要求 Requirements

• Flutter >=3.0.0 / Dart >=2.18.0
• iOS 12+，CocoaPods 依赖 AlicloudApmCrashAnalysis (>=2.3.6)
• Android minSdk 21，Gradle 8.x，依赖 com.aliyun.ams:alicloud-apm-crash-analysis:3.6.1
• 仅 Android/iOS 会真正启动 SDK，Web/Desktop 等平台会注册 AlicloudApmFallback

安装 Installation

1. 在 pubspec.yaml 添加依赖：

   dependencies:
     alicloud_apm: ^1.0.0
   

2. Android 仓库：在宿主工程的 settings.gradle（或 build.gradle 中的 repositories）加入阿里云仓库：

   dependencyResolutionManagement {
     repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
     repositories {
       google()
       mavenCentral()
       maven { url "https://maven.aliyun.com/nexus/content/repositories/releases/" }
     }
   }
   

3. iOS：执行 cd ios && pod install。

快速开始 Quick Start

import 'package:alicloud_apm/alicloud_apm.dart';
import 'package:flutter/material.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Apm.start(
    const ApmOptions(
      appKey: 'your-app-key',          // iOS/Android 分别向阿里云EMAS控制台申请
      appSecret: 'your-app-secret',
      appRsaSecret: 'your-app-rsa-secret',
    ),
  );

  runApp(const MyApp());
}

• 可使用 Apm.runGuarded(() => runApp(...)) 在 Apm.start 之前建立 guarded zone。
• 启动后可随时调用 Apm.setUserId / Apm.setUserNick / Apm.setCustomProperty / Apm.setCustomProperties 更新用户信息与自定义维度。

Crash Analysis 使用

// Isolate 监听
final isolate = await Isolate.spawn(doWork, null);
CrashAnalysis.watchIsolate(isolate);

// 记录自定义异常
try {
  throw StateError('Something went wrong');
} catch (error, stack) {
  await CrashAnalysis.recordException(error, stackTrace: stack);
}

// 手动构造异常模型
await CrashAnalysis.recordExceptionModel(
  ExceptionModel(
    name: 'ManualException',
    reason: 'Triggered from settings page',
    stackTrace: [StackFrame(symbol: 'HomePage.onTap')],
  ),
);

// 自定义日志
await CrashAnalysis.log('Your log message');

• 策略与堆栈深度：

  CrashAnalysisConfiguration.policy = ExceptionPolicy.reportImmediately; // disabled/record/reportImmediately
  CrashAnalysisConfiguration.stackTraceDepth = 64; // 0~256
  

运行时配置 Runtime Configuration

await ApmConfiguration.setLoggerLevel(LogLevel.info); // error/warning/notice/info/debug

示例与调试 Examples

• 完整示例位于 example/，覆盖启动、崩溃触发、自定义异常模型、用户维度等使用场景。
• 常用开发命令：flutter pub get、flutter analyze、flutter test。
• 建议发布前在真机运行 example 验证 iOS/Android 崩溃上报链路。

许可 License

Apache-2.0，详见 LICENSE。