Try it free

Instrument mobile apps with Dynatrace Flutter plugin in RUM Classic

  • Dynatrace Classic
  • How-to guide
  • 1-min read

The Dynatrace Flutter plugin adds the Dynatrace OneAgent for Android and iOS to your Flutter app and provides an API to use manual instrumentation for Flutter/Dart data capture.

For detailed technical documentation, see API for Flutter.

Prerequisites

Before you begin, ensure your environment meets the following requirements:

RequirementMinimum Version

Dynatrace version

1.203

Flutter

3.24.0

Dart

3.0.0

Android API Level

23

iOS SDK

15

Gradle

8.14.x

Android Gradle Plugin

8.1.1

Java

17

Set up a Flutter mobile app

  1. In Dynatrace, go to Mobile.

  2. Select Create mobile app.

  3. Enter a name for your application and select Create mobile app. The application settings page opens.

  1. From the application settings, select Instrumentation wizard > Flutter.

  2. Follow the steps described in the wizard.

Custom actions

A custom action measures a part of your app that automatic instrumentation doesn't detect. Web requests and values you report while the action is open are attached to it.

Create a custom action

Call enterAction() to open an action, and call leaveAction() to close it when the work is done.

DynatraceRootAction myAction = Dynatrace().enterAction('MyButton tapped');
//Perform the action and whatever else is needed.
myAction.leaveAction();

leaveAction() closes the action again. To report values for this action before closing, see Report values.

Action names are limited to 250 characters and will be truncated if they exceed this limit.

Cancel a custom action

Call cancel() instead of leaveAction() to discard an action. The action and all of its unfinished child actions are dropped and not sent to Dynatrace.

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
final myAction = Dynatrace().enterAction('MyAction');
myAction.cancel();

Create a custom sub action

Call enterAction() on an open action to group related work under it. The sub-action appears under its parent action.

DynatraceRootAction myAction = Dynatrace().enterAction('MyButton tapped');
DynatraceAction mySubAction = myAction.enterAction('MyButton Sub Action');
//Perform the action and whatever else is needed.
mySubAction.leaveAction();
myAction.leaveAction();
  • Only one level of nesting is supported. You can't create a sub-action of a sub-action.
  • Close the sub-action before you close its parent.
  • If you call enterAction() on an action that's already closed, it has no effect.

Report values

You can attach events, values, and errors to an open action. They appear on that action in the user session. Once an action is closed, nothing more can be reported on it.

Report values on an action

The following methods are available on any action returned by enterAction(), including sub-actions:

MethodReports

reportEvent(String eventName, {Platform? platform})

A named event

reportStringValue(String valueName, String value, {Platform? platform})

A string value

reportIntValue(String valueName, int value, {Platform? platform})

An integer value

reportDoubleValue(String valueName, double value, {Platform? platform})

A double value

reportError(String? errorName, int? errorCode, {Platform? platform})

An error with a numeric code

Use reportStringValue() to attach a string value to the action:

DynatraceRootAction myAction = Dynatrace().enterAction('MyButton tapped');
myAction.reportStringValue('ValueName', 'ImportantValue');
myAction.leaveAction();
  • Names and string values can be up to 250 characters. Longer values are truncated.
  • If a name is empty, the value isn't reported.

Report values without an action reference

If you don't have a reference to the action, call the same methods on Dynatrace(). The value is attached to the most recently opened action that is still open. If no action is open, the value isn't reported.

MethodReports

reportError(String? errorName, int? errorCode, {Platform? platform})

An error with a numeric code

reportErrorStacktrace(String errorName, String errorValue, String reason, String stacktrace, {Platform platform})

An error with name, value, reason, and stacktrace

reportEvent(String eventName, {Platform platform})

A named event

reportStringValue(String valueName, String value, {Platform platform})

A string value

reportIntValue(String valueName, int value, {Platform platform})

An integer value

reportDoubleValue(String valueName, double value, {Platform platform})

A double value

Use reportStringValue() to report a string value:

Dynatrace().reportStringValue('ValueName', 'ImportantValue');

All of these methods take an optional platform parameter that limits reporting to Android or iOS. See Platform-specific reporting.

Web request instrumentation

Our Flutter plugin provides a wrapper over Dart's http client. It can be used to automatically tag and time the web requests that are called.

Create a client

Create a client using Dynatrace().createHttpClient():

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
var client = Dynatrace().createHttpClient();
DynatraceRootAction webAction =
Dynatrace().enterAction('Button Click');
try {
await client.get(Uri.parse('https://dynatrace.com'));
} catch (error) {
// insert error handling here
} finally {
webAction.leaveAction();
client.close();
}

Attach requests to a custom action

Link web requests with a custom action. DynatraceHttpClient will automatically link a web request to the current open user action:

var client = Dynatrace().createHttpClient();
DynatraceRootAction webAction =
Dynatrace().enterAction('Button Click');
try {
await client.get(Uri.parse('https://dynatrace.com'));
} catch (error) {
// insert error handling here
}
try {
await client.get(Uri.parse('https://flutter.dev'));
} catch (error) {
// insert error handling here
}
try {
await client.get(Uri.parse('https://dart.dev'));
} catch (error) {
// insert error handling here
}
webAction.leaveAction();
client.close();

To wrap your own client, change how request sizes are calculated or to exclude URLs from monitoring, see Web request performance on the shared HTTP page.

Manual web request monitoring

Use manual web request monitoring when you can't use createHttpClient(), for example with dart:io HttpClient, gRPC, or another custom networking stack. The request is timed and attached to a user action.

Don't use manual monitoring and createHttpClient() for the same request, or the request is reported twice.

Monitor a web request

Use WebRequestTiming from a DynatraceRootAction to monitor a web request:

import 'dart:io';
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
final client = HttpClient();
final action = Dynatrace().enterAction('MyButton tapped - Web Action');
final timing = await action.createWebRequestTiming('https://dynatrace.com');
if (timing.getRequestTag().isNotEmpty) {
final request = await client.getUrl(Uri.parse('https://dynatrace.com'));
request.headers.set(timing.getRequestTagHeader(), timing.getRequestTag());
timing.startWebRequestTiming();
try {
final response = await request.close();
timing.stopWebRequestTiming(response.statusCode, response.reasonPhrase);
} catch (error) {
timing.stopWebRequestTiming(-1, error.toString());
}
}
action.leaveAction();

Crash reporting

Crash reporting is on by default. Once the plugin has started, it captures unhandled Dart and Flutter errors: Flutter framework errors (FlutterError.onError) and uncaught errors that reach PlatformDispatcher.instance.onError. Native crashes are captured by the native Android and iOS OneAgents.

Disable automatic crash reporting

Automatic crash reporting is enabled by default. If you prefer to handle error reporting manually, you can disable it in the configuration. To disable automatic crash reporting, set crashReporting to false in your dynatrace.config.yaml:

Android:

android:
config:
"dynatrace {
configurations {
defaultConfig {
crashReporting false
}
}
}"

iOS:

ios:
config:
"<key>DTXCrashReportingEnabled</key>
<false/>"

Or in case of manual startup:

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
void main() {
Dynatrace().start(
MyApp(),
configuration: Configuration(
beaconUrl: 'BeaconUrl',
applicationId: 'AppId',
reportCrash: false),
);
}

Deactivate automatic crash reporting

To deactivate automatic crash reporting, set crashReporting to false in your dynatrace.config.yaml:

android:
config:
"dynatrace {
configurations {
defaultConfig {
crashReporting false
}
}
}"
ios:
config:
"<key>DTXCrashReportingEnabled</key>
<false/>"

With manual startup, set reportCrash: false in the Configuration object:

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
void main() {
Dynatrace().start(
MyApp(),
configuration: Configuration(
beaconUrl: 'BeaconUrl',
applicationId: 'AppId',
reportCrash: false),
);
}

Report errors and crashes manually

MethodReported in RUM Classic as

reportZoneStacktrace(error, stacktrace)

Error

reportCrash(errorName, reason, stacktrace)

Crash

reportCrashWithException(crashName, exception, {reason, stacktrace})

Crash

Use reportZoneStacktrace() for caught exceptions that you want to see in Dynatrace:

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
Future<void> syncCart() async {
try {
throw Exception('Cart sync failed');
} catch (error, stacktrace) {
await Dynatrace().reportZoneStacktrace(error, stacktrace);
}
}

Capture errors from isolates

Errors in a spawned isolate don't reach the main isolate's error handlers. To report them, pass DynatraceIsolateErrorReceivePort as the isolate's onError port:

await Isolate.spawn(
(message){/*Do work*/},
null,
onError: DynatraceIsolateErrorReceivePort().sendPort,
);

If you already have an Isolate reference, you can call isolate.addDynatraceErrorListener() instead. Errors that occur before the listener is attached aren't reported:

final isolate = await Isolate.spawn((message){/*Do work*/}, null);
isolate.addDynatraceErrorListener();

User and location

Identify a user

Call identifyUser() to tag the current session with a username or ID. You can then search for that user's sessions in Dynatrace.

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
void onLoginSucceeded(String userId) {
Dynatrace().identifyUser(userId);
}

Report a GPS location

Report GPS location manually

Call setGPSLocation() to report the user's position. Dynatrace uses it to work out the city closest to that position.

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
void onLocationUpdated(double latitude, double longitude) {
Dynatrace().setGPSLocation(latitude, longitude);
}

Report GPS location automatically

The native OneAgents can also capture location automatically, as long as your app already requests location updates:

PlatformCaptures location fromDefault

Android

LocationListener implementations

Off. Turn on location monitoring in the android block of dynatrace.config.yaml. See Location monitoring.

iOS

CLLocationManager

On. Location is rounded to three decimal places to protect user privacy.

When location monitoring is turned off or no location information is available, Dynatrace uses IP addresses to determine the location of the user. For more information, see Detection of IP addresses, geolocations, and user agents in RUM Classic.

Business events

Call sendBizEvent() to report a business event, such as a completed booking or purchase. Business events are standalone: they aren't attached to a user action or user session. You can analyze them alongside your other business data in Dynatrace.

Dynatrace().sendBizEvent('com.easytravel.funnel.booking-finished', {
'event.name' : 'Confirmed Booking',
'screen': 'booking-confirmation',
'product': 'Danube Anna Hotel',
'amount': 358.35,
'currency': 'USD',
'reviewScore': 4.8,
'arrivalDate': '2022-11-05',
'departureDate': '2022-11-15',
'journeyDuration': 10,
'adultTravelers': 2,
'childrenTravelers': 0
});

The sendBizEvent() method supports the following parameters:

ParameterDescription

type

Required. The event type, for example com.easytravel.funnel.booking-finished.

attributes

Optional map of event attributes. Pass null or an empty map to send the event with only the attributes Dynatrace adds.

platform

Optional platform to report the event on.

Platform-specific reporting

By default, API calls report on both Android and iOS. To report on only one platform, pass the optional platform parameter with Platform.Android or Platform.iOS. On the other platform, the call does nothing.

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';
// Reported on iOS only
final iosAction = Dynatrace().enterAction('MyButton tapped', platform: Platform.iOS);
iosAction.leaveAction();
// Reported on Android only
final androidAction = Dynatrace().enterAction('MyButton tapped', platform: Platform.Android);
androidAction.leaveAction();
// Reported on both platforms
final action = Dynatrace().enterAction('MyButton tapped');
action.leaveAction();

For a full list of APIs, see API for Flutter.

Related tags
Digital ExperienceMobileMobile