Cloud Monitor:SDK configuration reference

Start configuration

The start method is the core startup method of the AlibabaCloudRUM Flutter SDK. It initializes the monitoring system and starts the application.

Future<void> start(Widget topLevelWidget, {Function()? beforeRunApp}) async

Example:

AlibabaCloudRUM().start(
  // Root widget
  MyApp(),
  beforeRunApp: () async => {
    // You must call the following method before this callback completes
    WidgetsFlutterBinding.ensureInitialized(),
    // Other business logic
    // ...
    },
);

Advanced start configuration

In addition to the start method, you can use the initialize method to start the SDK. When you use this method, you must call WidgetsFlutterBinding.ensureInitialized before calling initialize.

Future<void> initialize();

Example:

// Make sure to call WidgetsFlutterBinding.ensureInitialized before calling initialize
WidgetsFlutterBinding.ensureInitialized();
// Call the initialize method to initialize the SDK
AlibabaCloudRUM().initialize();
// Remember to call runApp
runApp(MyApp());

Register a routing listener

The SDK provides AlibabaCloudRUMNavigationObserver to monitor Flutter route changes.

AlibabaCloudRUMNavigationObserver({
    List<String>? ignoreRoutes,
    bool enablePagePerf = true,
})

Example:

class MyApp extends StatelessWidget {
  MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      // ...
      navigatorObservers: [
        // Register an AlibabaCloudRUMNavigationObserver instance for route monitoring
        AlibabaCloudRUMNavigationObserver(ignoreRoutes: ['home_page'], enablePagePerf: true)
      ],
    );
  }
}

Register an action collector

The SDK provides AlibabaCloudActionCapture for automatically collecting user click actions in Flutter applications. Register it once at the root Widget of your application and use it to wrap MaterialApp or CupertinoApp.

const AlibabaCloudActionCapture({
  Key? key,
  required Widget child,
  CustomGestureElementCapture? customGestureElementCapture,
})

Basic example:

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return AlibabaCloudActionCapture(
      child: MaterialApp(
        home: const MyHomePage(),
        routes: {
          // ...
        },
        navigatorObservers: [
          AlibabaCloudRUMNavigationObserver(
            ignoreRoutes: ['home_page'],
            enablePagePerf: true,
          ),
        ],
      ),
    );
  }
}

const ActionAnnotation({
  Key? key,
  required String description,
  required Widget child,
  Map<String, Object?>? attributes,
})

ActionAnnotation(
  description: 'Submit Order',
  attributes: const {
    'page': 'checkout',
    'business_action': 'submit_order',
  },
  child: ElevatedButton(
    onPressed: () {
      // Submit order.
    },
    child: const Text('Submit'),
  ),
)

typedef CustomGestureElementCapture = GestureCaptureInfo? Function(
  Widget widget,
);

const GestureCaptureInfo(
  String elementName, {
  bool searchForBetter = false,
  bool searchForText = true,
})

class BusinessActionWidget extends StatelessWidget {
  const BusinessActionWidget({
    super.key,
    required this.child,
  });

  final Widget child;

  @override
  Widget build(BuildContext context) => child;
}

GestureCaptureInfo? recognizeBusinessAction(Widget widget) {
  if (widget is BusinessActionWidget) {
    return const GestureCaptureInfo(
      'BusinessAction',
      searchForBetter: false,
      searchForText: true,
    );
  }

  // Return null to fall back to the SDK's default recognition logic.
  return null;
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return AlibabaCloudActionCapture(
      customGestureElementCapture: recognizeBusinessAction,
      child: MaterialApp(
        home: Scaffold(
          body: BusinessActionWidget(
            child: ElevatedButton(
              onPressed: () {
                // Add to shopping cart.
              },
              child: const Text('Add to Cart'),
            ),
          ),
        ),
      ),
    );
  }
}

Print error information

When the SDK captures a Flutter exception, it calls FlutterError.dumpErrorToConsole by default to print the error information to the console. You can enable or disable this feature with the setDumpError method.

void setDumpError(bool enable)

Example:

// Disable printing error information to the console
AlibabaCloudRUM().setDumpError(false);

Flutter error callback

Flutter does not support cascading error monitoring, so the original error listeners in your application become inactive after the AlibabaCloudRUM SDK intercepts synchronous and asynchronous errors. The SDK provides a unified error callback interface to address this.

void onRUMErrorCallback(bool callback(Object? error, StackTrace? stack, bool isAsync))

Callback parameters:

Callback return value:

Example:

AlibabaCloudRUM().onRUMErrorCallback((error, stack, isAsync) {
  // Handle the error event
  // ...
  // logger.d('debuggg error: $error, stack: $stack');

  // Return true to let the SDK report the error
  return true;
});

Get the device ID

The SDK generates a device ID by default. Use the getDeviceId method to retrieve it.

Future<String?> getDeviceId() async

Example:

AlibabaCloudRUM().getDeviceId().then(((value) => {print("deviceId: ${value}")}));

Set a custom username

Set user-related information to associate data analysis with actual users.

Future<void> setUserName(String userID) async

Example:

AlibabaCloudRUM().setUserName("xxxxx");

Set custom user extra information

Set user-related information to associate data analysis with actual users.

• Set user extra information. This method uses the overwrite mode. Calling this method overwrites all previously configured user extra information.

  Future<void> setUserExtraInfo(Map<String, dynamic> extraInfo) async

  Parameter	Description	Constraints	Failure result
  extraInfo	The user extra information.	The map can be empty or null. The JSON-serialized length must be 7,000 characters or less. Otherwise, the API call fails.	API call fails. The setting does not take effect.

  Example:

  AlibabaCloudRUM().setUserExtraInfo({"shopId": "xxxxx", "shopName": "yyyyy"});

• Append user extra information. This method uses the append mode.

  Future<void> addUserExtraInfo(Map<String, dynamic> extraInfo) async

  Parameter	Description	Constraints	Failure result
  extraInfo	The user extra information.	The map can be empty or null. The JSON-serialized length must be 7,000 characters or less. Otherwise, the API call fails.	API call fails. The setting does not take effect.

  Example:

  AlibabaCloudRUM().addUserExtraInfo({"userId": "11111111"});

Set custom global extra information

Set global extra information to associate data analysis with actual users.

• Set global extra information. This method uses the overwrite mode. Calling this method overwrites all previously configured global extra information.

  Future<void> setExtraInfo(Map<String, dynamic> extraInfo) async

  Parameter	Description	Constraints	Failure result
  extraInfo	The global extra information.	The map can be empty or null. The JSON-serialized length must be 7,000 characters or less. Otherwise, the API call fails.	API call fails. The setting does not take effect.

  Example:

  AlibabaCloudRUM().setExtraInfo({"global_key": "global_value", "global_key2": "global_value2"});

• Append global extra information. This method uses the append mode.

  Future<void> addExtraInfo(Map<String, dynamic> extraInfo) async

  Parameter	Description	Constraints	Failure result
  extraInfo	The global extra information.	The map can be empty or null. The JSON-serialized length must be 7,000 characters or less. Otherwise, the API call fails.	API call fails. The setting does not take effect.

  Example:

  AlibabaCloudRUM().addExtraInfo({"global_userId": "2222222222"});

Report custom exceptions

Call the custom exception API to report custom exception data.

Future<void> setCustomException(String exceptionType, String causedBy, String errorDump)

Example:

AlibabaCloudRUM().setCustomException("custom exception type", 
    "caused by customer", 
    "Custom error dump");

Report custom events

Report custom events by calling the corresponding API with the required parameters.

Future<void> setCustomEvent(String name, {String? group, String? snapshots, double? value, Map<String, String>? attributes})

Example:

AlibabaCloudRUM().setCustomEvent("search_shop",
    group: "shop",
    snapshots: 'Search: ${search.toString()}',
    value: 1,
    attributes: {"search": "xxxxx"});

Report custom logs

Report custom log information by calling the corresponding API with the required parameters.

Future<void> setCustomLog(String logInfo, {String? name, String? snapshots, String? level, Map<String, String>? attributes})

Example:

AlibabaCloudRUM().setCustomLog("2024-08-20 14:00:05 Print shopinfo info.",
    name: "shop",
    snapshots: 'Shop: ${shop.toString()}',
    level: "DEBUG",
    attributes: {"shopId": "xxxxx", "shopName": "yyyyy"});

Resource snapshot collection

The SDK supports collecting HTTP request/response headers and payload information. By default, no resource snapshot data is collected. You must explicitly enable this feature using the APIs described in the following sections.

HttpClient

You must set ResourceSnapshotProvider to explicitly enable snapshot collection for the HttpClient library.

void setResourceSnapshotProvider(ResourceSnapshotProvider? provider)

ResourceSnapshotUtils utility class

Because HttpClientRequest is a write-only stream and HttpClientResponse is a read-only stream, you must use the utility class to cache the data.

Example:

AlibabaCloudRUM().setResourceSnapshotProvider(
  ResourceSnapshotProvider(
    onRequestHeaders: (request) {
      return {
        'content-type': request.headers.value('content-type') ?? '',
      };
    },
    onRequestPayload: (request) {
      // Because the request object does not retain the payload, you must use the ResourceSnapshotUtils class
      // to call the ResourceSnapshotUtils.cacheRequestBody method to cache the payload data when the request is sent
      final body = ResourceSnapshotUtils.getCachedRequestBody(request);
      if (body == null) return null;
      // Make sure to desensitize the data
      return body.replaceAll(RegExp(r'"password":\s*"[^"]*"'), '"password":"***"');
    },
    onResponsePayload: (response) {
      // Response payload collection is not supported
      return null;
    },
  ),
);

AlibabaCloudRUMDioInterceptor({DioResourceSnapshotProvider? onProvideSnapshots})

final dio = Dio();
// Add AlibabaCloudRUMDioInterceptor
dio.interceptors.add(
  AlibabaCloudRUMDioInterceptor(
    onProvideSnapshots: (requestOptions, response, error) {
      // The following code is for reference only. Desensitize the data based on your business requirements
      final headers = <String, Object>{};
      response?.headers.forEach((name, value) {
        headers[name] = value;
      });
      return ResourceSnapshots(
        requestHeaders: {...requestOptions.headers},
        requestPayload: requestOptions.data,
        responseHeaders: {...headers},
        responsePayload: jsonEncode(response?.data),
      );
    },
  ),
);
// Other code omitted

Important notes

• The SDK does not collect any headers or payload data by default. You must explicitly enable the feature using the APIs described in this section.

• The caller of the SDK is responsible for data desensitization. The SDK does not automatically filter any sensitive information, including but not limited to passwords and personally identifiable information (PII).