Flutter应用性能监控插件azure_application_insights的使用

Azure Application Insights简介

Azure Application Insights 是一个强大的工具，用于理解你的软件系统是如何运作的。在Flutter应用程序的上下文中，它允许你深入了解用户交互、性能和应用程序中的故障。

如何使用？

安装与导入

首先，你需要安装azure_application_insights包，然后将其导入到你的Dart代码中：

import 'package:azure_application_insights/azure_application_insights.dart';

配置TelemetryClient

要与Application Insights集成，唯一需要的信息是你的连接字符串，可以在Azure门户中的“概览”选项卡找到它。

一旦有了连接字符串，你可以构造一个TelemetryClient实例，如下所示：

final processor = BufferedProcessor(
  next: TransmissionProcessor(
    connectionString: connectionString,
    httpClient: client,
    timeout: const Duration(seconds: 10),
  ),
);

final telemetryClient = TelemetryClient(
  processor: processor,
);

这是一般的设置，其中遥测项在传输前会被缓冲。根据你的处理需求，可能需要在一个应用程序中拥有多个TelemetryClient实例。例如，你可能有一个TelemetryClient用于缓冲所有非错误遥测项，另一个不进行缓冲，专门用于尽快提交错误。

发送遥测数据

一旦创建了TelemetryClient，可以通过调用各种方法来捕获遥测项：

telemetryClient.trackTrace(
  severity: Severity.information,
  message: 'Hello from Dart!',
);

还可以配置额外的属性与遥测项一起提交。这些属性可以在两个地方配置：

1. 关联的TelemetryContext：这些属性将附加到通过该客户端提交的所有遥测项。
2. 每个遥测项的方法参数：这些属性仅附加到特定的遥测项。

示例代码如下：

// 设置全局属性
telemetryClient.context
  ..applicationVersion = 'my version'
  ..device.type = 'Android'
  ..properties['environmentName'] = 'dev';

// 发送带有个别属性的遥测项
telemetryClient.trackTrace(
  severity: Severity.information,
  message: 'An example',
  additionalProperties: {'answer': 42},
);

Flutter集成

为了在Flutter应用中提交崩溃信息作为遥测数据，可以使用以下代码片段：

void main() {
  if (kReleaseMode) {
    runWithCrashReporting(codeToExecute: run);
  } else {
    run();
  }
}

void run() => runApp(MyApp());

Future<void> runWithCrashReporting({
  required VoidCallback codeToExecute,
}) async {
  FlutterError.onError = (details) => submitErrorAsTelemetry(
        isFatal: true,
        error: details.exception,
        trace: details.stack,
      );

  runZonedGuarded(
    codeToExecute,
    (error, trace) => submitErrorAsTelemetry(
      isFatal: true,
      error: error,
      trace: trace,
    ),
  );
}

Future<void> submitErrorAsTelemetry({
  required bool isFatal,
  required Object error,
  required StackTrace trace,
}) async {
  try {
    final telemetryClient = ...;
    final errorProperties = ...;

    telemetryClient.trackError(
      error: error,
      stackTrace: trace,
      severity: isFatal ? Severity.critical : Severity.error,
      additionalProperties: errorProperties,
    );

    if (isFatal) {
      await telemetryClient.flush();
    }
  } on Object catch (e, t) {
    debugPrintSynchronously('Sending error telemetry failed: $e\r\n$t');
    debugPrintSynchronously('Original error: $error');
  } finally {
    if (isFatal && kReleaseMode) {
      debugPrintSynchronously('Forcing exit');
    }
  }
}

HTTP中间件

对于HTTP请求，可以使用TelemetryHttpClient自动记录依赖项遥测信息：

final telemetryHttpClient = TelemetryHttpClient(
  telemetryClient: telemetryClient,
  inner: Client(),
);

await telemetryHttpClient.get('https://example.com/');

示例完整代码

下面是一个完整的示例代码，展示了如何在Flutter应用中使用azure_application_insights插件：

// ignore_for_file: cascade_invocations

import 'package:azure_application_insights/azure_application_insights.dart';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

const connectionString = 'TODO'; // 替换为你的连接字符串

void main() {
  if (kReleaseMode) {
    runWithCrashReporting(codeToExecute: () => runApp(MyApp()));
  } else {
    runApp(MyApp());
  }
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  MyHomePage({Key? key, required this.title}) : super(key: key);

  final String title;

  @override
  _MyHomePageState createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  int _counter = 0;

  void _incrementCounter() {
    setState(() {
      _counter++;
    });

    sendTelemetry();
  }

  Future<void> sendTelemetry() async {
    print('Sending telemetry...');

    try {
      final client = http.Client();

      final processor = BufferedProcessor(
        next: TransmissionProcessor(
          connectionString: connectionString,
          httpClient: client,
          timeout: const Duration(seconds: 10),
        ),
      );

      final telemetryClient = TelemetryClient(
        processor: processor,
      );

      telemetryClient.context
        ..applicationVersion = 'example'
        ..user.id = 'somebody'
        ..properties['custom'] = 'a custom property value';

      telemetryClient.trackTrace(
        severity: Severity.information,
        message: 'Hello from Dart!',
      );

      telemetryClient.trackTrace(
        severity: Severity.verbose,
        message: 'Here is a trace with additional properties',
        additionalProperties: {'answer': 42},
      );

      telemetryClient.trackEvent(
        name: 'started',
        additionalProperties: {
          'timestamp': DateTime.now().toUtc().toIso8601String(),
        },
      );

      final telemetryHttpClient = TelemetryHttpClient(
        telemetryClient: telemetryClient,
        inner: client,
      );
      await telemetryHttpClient.get(Uri.parse('https://example.com/'));

      await telemetryClient.flush();

      client.close();

      print('...sent!');
    } on Object catch (e) {
      print('...failed! $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'You have pushed the button this many times:',
            ),
            Text(
              '$_counter',
              style: Theme.of(context).textTheme.headline4,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: Icon(Icons.add),
      ),
    );
  }
}

Future<void> runWithCrashReporting({
  required VoidCallback codeToExecute,
}) async {
  FlutterError.onError = (details) => submitErrorAsTelemetry(
        isFatal: true,
        error: details.exception,
        trace: details.stack,
      );

  runZonedGuarded(
    codeToExecute,
    (error, trace) => submitErrorAsTelemetry(
      isFatal: true,
      error: error,
      trace: trace,
    ),
  );
}

Future<void> submitErrorAsTelemetry({
  required bool isFatal,
  required Object error,
  required StackTrace trace,
}) async {
  try {
    final telemetryClient = ...; // 获取TelemetryClient实例
    final errorProperties = ...; // 获取任何其他属性

    telemetryClient.trackError(
      error: error,
      stackTrace: trace,
      severity: isFatal ? Severity.critical : Severity.error,
      additionalProperties: errorProperties,
    );

    if (isFatal) {
      await telemetryClient.flush();
    }
  } on Object catch (e, t) {
    debugPrintSynchronously('Sending error telemetry failed: $e\r\n$t');
    debugPrintSynchronously('Original error: $error');
  } finally {
    if (isFatal && kReleaseMode) {
      debugPrintSynchronously('Forcing exit');
    }
  }
}

通过上述步骤，你可以在Flutter应用中成功集成并使用azure_application_insights插件进行性能监控。