Flutter性能监控插件datadog_flutter_plugin的使用

Overview

Datadog Real User Monitoring (RUM)使您能够可视化和分析Flutter应用程序中单个用户的实时性能和用户旅程。根据不同的版本，Datadog RUM SDK对Flutter的支持情况如下：

• Datadog RUM SDK versions < 1.4 支持监测Flutter 2.8+
• Datadog RUM SDK versions >= 1.4 支持监测Flutter 3.0+
• Datadog RUM SDK versions >= 2.6 支持监测Flutter 3.19+

完整的文档请参阅官方Datadog文档。

Current Datadog SDK Versions

注意事项

• iOS: Podfile必须包含use_frameworks!（在Flutter中默认启用），并且目标iOS版本>=12.0。
• Android: minSdkVersion必须>=21，如果使用Kotlin，其版本应>=1.8.0。
• Web: 需要在index.html的head标签下添加以下代码来加载CDN提供的Datadog Browser SDKs for Logs和RUM。

<script type="text/javascript" src="https://www.datadoghq-browser-agent.com/us1/v5/datadog-logs.js"></script> 
<script type="text/javascript" src="https://www.datadoghq-browser-agent.com/us1/v5/datadog-rum-slim.js"></script> 

Setup

为了设置Log Management或Real User Monitoring (RUM)，可以使用Datadog Flutter Plugin。以下是配置和初始化的详细步骤。

Create Configuration Object

创建一个配置对象用于每个Datadog特性（如Logs和RUM）。可以通过下面的代码片段创建：

final trackingConsent = ... // 确定用户的跟踪同意状态
final configuration = DatadogConfiguration(
  clientToken: '<CLIENT_TOKEN>',
  env: '<ENV_NAME>',
  site: DatadogSite.us1,
  nativeCrashReportEnabled: true,
  loggingConfiguration: DatadogLoggingConfiguration(),
  rumConfiguration: DatadogRumConfiguration(
    applicationId: '<RUM_APPLICATION_ID>',
  )
);

更多配置选项请参阅DatadogConfiguration对象文档。

Initialize the Library

可以在main.dart文件中以两种方式之一初始化RUM：

使用DatadogSdk.runApp

这种方式会自动设置错误报告。

await DatadogSdk.runApp(configuration, () async {
  runApp(const MyApp());
});

手动设置错误跟踪和资源跟踪

如果不使用DatadogSdk.runApp，需要先调用WidgetsFlutterBinding.ensureInitialized，然后手动设置错误处理逻辑。

WidgetsFlutterBinding.ensureInitialized();
final originalOnError = FlutterError.onError;
FlutterError.onError = (details) {
  FlutterError.presentError(details);
  DatadogSdk.instance.rum?.handleFlutterError(details);
  originalOnError?.call(details);
};
final platformOriginalOnError = PlatformDispatcher.instance.onError;
PlatformDispatcher.instance.onError = (e, st) {
  DatadogSdk.instance.rum?.addErrorInfo(
    e.toString(),
    RumErrorSource.source,
    stackTrace: st,
  );
  return platformOriginalOnError?.call(e, st) ?? false;
};
await DatadogSdk.instance.initialize(configuration);

runApp(const MyApp());

Send Logs

初始化Datadog并配置了DatadogLoggingConfiguration后，可以通过DatadogLogger发送日志到Datadog。

final logger = DatadogSdk.instance.logs?.createLogger(
  DatadogLoggerConfiguration(
    remoteLogThreshold: LogLevel.warning,
  ),
);
logger?.debug("A debug message.");
logger?.info("Some relevant information?");
logger?.warn("An important warning…");
logger?.error("An error was met!");

也可以自定义日志器的服务名和名称。

final secondLogger = DatadogSdk.instance.createLogger(
  LoggingConfiguration({
    service: 'my_app.additional_logger',
    name: 'Additional logger'
  })
);

secondLogger.info('Info from my additional logger.');

Track RUM Views

可以使用DatadogNavigationObserver自动跟踪命名路由。

MaterialApp(
  home: HomeScreen(),
  navigatorObservers: [
    DatadogNavigationObserver(DatadogSdk.instance),
  ],
);

或者使用DatadogRouteAwareMixin和DatadogNavigationObserverProvider属性来自动开始和停止RUM视图。

class _MyHomeScreenState extends State<MyHomeScreen>
    with RouteAware, DatadogRouteAwareMixin {

  @override
  RumViewInfo get rumViewInfo => RumViewInfo(name: 'MyHomeScreen');
}

对于重命名视图或提供自定义路径，可以通过viewInfoExtractor回调函数实现。

RumViewInfo? infoExtractor(Route<dynamic> route) {
  var name = route.settings.name;
  if (name == 'my_named_route') {
    return RumViewInfo(
      name: 'MyDifferentName',
      attributes: {'extra_attribute': 'attribute_value'},
    );
  }

  return defaultViewInfoExtractor(route);
}

var observer = DatadogNavigationObserver(
  datadogSdk: DatadogSdk.instance,
  viewInfoExtractor: infoExtractor,
);

Automatic Resource Tracking

通过Datadog Tracking HTTP Client包可以自动跟踪资源和HTTP请求。只需在pubspec.yaml中添加该包，并在初始化时进行配置。

final configuration = DatadogConfiguration(
  // 配置信息
  firstPartyHosts: ['example.com'],
)..enableHttpTracking()

为了启用Datadog分布式追踪，需要在DatadogConfiguration.firstPartyHosts属性中设置支持分布式追踪的域名。还可以通过设置DatadogRumConfiguration中的traceSampleRate来修改采样率。

示例代码

以下是一个完整的示例代码，展示了如何在Flutter应用中集成Datadog RUM SDK。

import 'package:datadog_flutter_plugin/datadog_flutter_plugin.dart';
import 'package:flutter/material.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';

import 'example_app.dart';

void main() async {
  await dotenv.load();

  var applicationId = dotenv.maybeGet('DD_APPLICATION_ID');

  final configuration = DatadogConfiguration(
    clientToken: dotenv.get('DD_CLIENT_TOKEN', fallback: ''),
    env: dotenv.get('DD_ENV', fallback: ''),
    service: 'com.datadoghq.example.flutter',
    version: '1.2.3',
    site: DatadogSite.us1,
    nativeCrashReportEnabled: true,
    loggingConfiguration: DatadogLoggingConfiguration(),
    rumConfiguration: applicationId != null
        ? DatadogRumConfiguration(
            sessionSamplingRate: 100.0,
            applicationId: applicationId,
            detectLongTasks: true,
            reportFlutterPerformance: true,
            actionEventMapper: (event) {
              if (event.action.target?.name == 'Test Action') {
                event.action.target?.name = 'Replaced';
              }
              return event;
            },
          )
        : null,
  );

  final ddsdk = DatadogSdk.instance;
  ddsdk.sdkVerbosity = CoreLoggerLevel.debug;
  DatadogSdk.runApp(configuration, TrackingConsent.granted, () async {
    return runApp(const ExampleApp());
  });
}

这个示例代码展示了如何加载环境变量、配置Datadog RUM SDK以及启动应用程序。希望这些内容能帮助你更好地理解和使用Datadog Flutter Plugin。