dynatrace_flutter_plugin_dio 3.327.1

An extension of the Dynatrace Flutter Plugin which allows support for instrumentation of the Dio package.

Dynatrace Flutter Plugin support with Dio

This plugin adds support/instrumentation for dio when used with the Dynatrace Flutter Plugin.

Requirements

• Dynatrace Flutter Plugin.
• Flutter Version >= 1.12.0
• Dart Version >= 2.15
• Dio Version >= 5.0.0
• Gradle: >= 5.x
• Android API Level >= 21
• iOS SDK >= 12

Overview

• Usage
• Request & Response size calculation
• New RUM experience preview
  • Http Event Modifier

Usage

Our plugin for Dio provides an extension method, .instrument(), which can be used to automatically tag and time the web requests that are called with the Dio package.

import 'package:dynatrace_flutter_plugin_dio/dynatrace_flutter_plugin_dio.dart';

final dio = Dio();
dio.instrument
();

Create a user action and correlate the dio request shown in the Waterfall analysis:

import 'package:dynatrace_flutter_plugin_dio/dynatrace_flutter_plugin_dio.dart';
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';

final dio = Dio();
dio.instrument();

var url = 'https://dynatrace.com';
DynatraceRootAction dioAction = Dynatrace().enterAction('Dio Action');

try {
  await dio.get(url);
} catch (error) {
  // insert error handling here
} finally {
  dioAction.leaveAction();
}

Note: If you do not create a user action around the dio request, our plugin will automatically create a user action which will include the request in the Waterfall analysis of such action. The name of this action is **Dio Request:

Request & Response size calculation

The web request instrumentation is by default reporting request and response bytes. This calculation has some limitations, therefore the instrument function allows you to pass DynatraceClientAdapterOptions. Per default, Dio will append following headers:

• "Accept-Encoding": "gzip"
• "User-Agent": "Dart/X.X (dart:io)"

These headers are not visible at the request size calculation, but can be modified via HttpClient used in Dio (e.g request.headers.removeAll(HttpHeaders.acceptEncodingHeader)). If the header value will be overridden by a different value, our calculation will not be able to consider this as we expect the default header value. For example, if " Accept-Encoding" is removed, use DynatraceClientAdapterOptions to get correct values for the request size calculation (see the example below). If headers are changed on request basis and a different "Accept-Encoding" value is appended directly, the calculation will consider this. Also DynatraceClientAdapterOptions provides functionality for excluding urls which you do not want to be tracked.

import 'package:dynatrace_flutter_plugin_dio/dynatrace_flutter_plugin_dio.dart';
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';

Map<String, String> _myNewDefaultHeaders = {
  "User-Agent": "Dart/X.X (dart:io)"
};
DynatraceClientAdapterOptions _options = DynatraceClientAdapterOptions(
        _myNewDefaultHeaders, 
        exclusionList: ['url-to-exclude.com'],
);

final dio = Dio();
dio.instrument(options: _options);

var url = 'https://dynatrace.com';
DynatraceRootAction dioAction =
Dynatrace().enterAction('Dio Action');

try {
await dio.get(url);
} catch (error) {
// insert error handling here
} finally {
dioAction.leaveAction();
}

New RUM experience preview

⚠️ Preview Feature: The New RUM Experience APIs are currently in preview and may be subject to changes. These APIs provide enhanced event tracking capabilities with the new Dynatrace RUM on Grail feature.

The New RUM Experience introduces a set of advanced APIs that allow you to send custom events, modify event data, and track views in your Flutter application. These APIs provide more granular control over the data captured by Dynatrace.

For more detailed information about the New RUM Experience, see the Dynatrace documentation.

Http Event Modifier

Dio HTTP event modifiers allow you to intercept and modify HTTP request events before they are sent to Dynatrace. This is particularly useful for adding custom properties, redacting sensitive information, or filtering specific requests. Common use cases include:

• Adding custom properties to HTTP events (e.g., API version, user context)
• Redacting sensitive information from URLs, headers, or request/response data
• Filtering out specific HTTP requests (e.g., health checks, internal APIs)
• Enriching events with additional business context
• Categorizing requests by endpoint or functionality

Creating a Dio HTTP Event Modifier

A Dio HTTP event modifier is a function that receives the event data along with Dio-specific request and response details, and returns either a modified event or null to discard it. Only events from Dio requests will be affected by these modifiers.

import 'package:dynatrace_flutter_plugin_dio/dynatrace_flutter_plugin_dio.dart';
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';

// Define the modifier function
final dioModifier = (event, request, response, error, stackTrace) {
  // Add custom properties to all HTTP events
  event['event_properties.api_version'] = 'v2';
  event['event_properties.request_source'] = 'mobile_app';
  
  // Redact user IDs from URLs for privacy
  // Example: https://api.example.com/users/abc123/profile -> https://api.example.com/users/{id}/profile
  if (event.containsKey('url.full')) {
    event['url.full'] = event['url.full']
        .toString()
        .replaceAll(RegExp(r'/users/\w+/'), '/users/{id}/');
  }
  
  // Filter out health check requests
  if (request.path.contains('/health')) {
    return null; // Discard this event
  }
  
  // Access Dio-specific response details
  if (response != null) {
    event['event_properties.response_size'] = response.data?.toString().length ?? 0;
    event['event_properties.response_type'] = response.data.runtimeType.toString();
  }
  
  return event;
};

// Add the modifier
Dynatrace().addDioHttpEventModifier(dioModifier);

// Use Dio with instrumentation
final dio = Dio();
dio.instrument();

// Make a request to see the modifier in action
await dio.get('https://dynatrace.com');

Removing Dio HTTP Event Modifiers

When you no longer need a modifier, you can remove it:

import 'package:dynatrace_flutter_plugin_dio/dynatrace_flutter_plugin_dio.dart';
import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';

// Define the modifier
final myModifier = (Map<String, dynamic> event, RequestOptions request, Response? response, dynamic error,
    StackTrace? stackTrace) {
  event['event_properties.custom_field'] = 'value';
  return event;
};

// Add the modifier
Dynatrace().addDioHttpEventModifier(myModifier);

// Remove it when no longer needed
Dynatrace().removeDioHttpEventModifier(myModifier);

Modifier Parameters

The Dio HTTP event modifier function receives five parameters:

Parameter	Type	Description
event	Map<String, dynamic>	The HTTP event data to be modified. Contains fields like url.full, http.request.method, http.response.status_code, etc.
request	RequestOptions	The Dio request options object with details like method, URL, headers, query parameters, and request data
response	Response<dynamic>?	The Dio response object (null if the request failed before receiving a response)
error	dynamic	Any error that occurred during the request (null for successful requests). Can be a DioException or other error type
stackTrace	StackTrace?	The stack trace associated with an error (null for successful requests)

Modifiable Fields

Most standard Dynatrace RUM HTTP event fields are read-only. The following fields can be modified:

• url.full - The complete request URL
• event_properties.* - Custom properties with this prefix

Important Considerations

• Execution order: Modifiers are executed in the order they were added
• Returning null: If a modifier returns null, the event is discarded and subsequent modifiers won't be called
• Performance: Modifiers should be efficient as they are called for every HTTP request made through Dio
• Field naming: Custom properties must follow the event_properties. prefix naming convention
• Reserved fields: Most core HTTP fields (method, status code, etc.) cannot be modified
• Error handling: If a modifier throws an exception, it will be logged but won't prevent other modifiers from executing
• Dio-specific: These modifiers only affect HTTP events from instrumented Dio requests