Try it free

Custom events

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

Dynatrace allows you to send custom events to track business metrics or application-specific data. You can also enrich all events with additional context using event modifiers.

Event and session properties

Allow event and session properties

Before you can send event or session properties from your application, you must first allow each property key in Dynatrace. Any properties that are not allowed will be dropped during ingest.

To allow a key, follow the steps in Allow API-reported properties.

Send custom events

Use sendEvent() to report custom events with properties. Property keys must be prefixed with event_properties..

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';


double value = 149.99;


// Using constructor
Dynatrace().sendEvent(EventData(
  duration: 250,
  eventProperties: {
    'event_properties.checkout_step': 'payment_confirmed',
    'event_properties.cart_value': value,
    'event_properties.item_count': 3,
  },
));


// Using addEventProperty method
final event = EventData(duration: 250)
  ..addEventProperty('event_properties.checkout_step', 'payment_confirmed')
  ..addEventProperty('event_properties.item_count', 3);
if (value > 0) {
  event.addEventProperty('event_properties.cart_value', value);
}


Dynatrace().sendEvent(event);

Property naming rules

For naming rules and limits, see Event and session properties.

Event modifiers

Event modifiers allow you to intercept and modify all events before they are sent to Dynatrace. Use them to add common properties, redact sensitive information, or filter events.

Add an event modifier

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';


Dynatrace().addEventModifier((event) {
  // Add experiment tracking to all events
  event['event_properties.experiment_id'] = 'checkout_flow_v2';
  event['event_properties.variant'] = 'treatment_a';
  return event;
});

Remove event modifiers

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';


// Define the modifier
Map<String, dynamic>? myModifier(Map<String, dynamic> event) {
  event['event_properties.custom'] = 'value';
  return event;
}


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


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

Modifier limitations

Event modifiers have restrictions on which fields can be modified to ensure data integrity.

Modifiable fields

The following fields can be modified or added:

  • event_properties.*—event properties.
  • session_properties.*—session properties (only on session property events).
  • url.full—complete request URL.
  • exception.stack_trace—exception stack traces.

All other fields are read-only and can't be modified. The original values are preserved.

Important considerations

  • Thread safety—modifiers may be called from any thread; ensure your code is thread-safe.
  • Performance—keep modifiers efficient; they run for every event.

Modifier examples

Filter events

Return null to discard an event:

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';


Dynatrace().addEventModifier((event) {
  // Filter out events from test users
  if (event['event_properties.is_test_user'] == true) {
    return null; // Discard this event
  }
  return event;
});

Redact sensitive data

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';


Dynatrace().addEventModifier((event) {
  // Redact user IDs from URLs
  if (event.containsKey('url.full')) {
    event['url.full'] = event['url.full']
        .toString()
        .replaceAll(RegExp(r'/users/\w+/'), '/users/{id}/');
  }
  return event;
});

Add feature flags

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';


void setupFeatureFlagTracking(Map<String, bool> featureFlags) {
  Dynatrace().addEventModifier((event) {
    for (final entry in featureFlags.entries) {
      event['event_properties.ff_${entry.key}'] = entry.value;
    }
    return event;
  });
}

Conditional event enrichment

import 'package:dynatrace_flutter_plugin/dynatrace_flutter_plugin.dart';


void setupConditionalEnrichment() {
  Dynatrace().addEventModifier((event) {
    // Only enrich HTTP events
    if (event.containsKey('http.request.method')) {
      event['event_properties.api_client'] = 'flutter_app';
      event['event_properties.api_version'] = 'v2';
    }


    // Only enrich error events
    if (event.containsKey('exception.type')) {
      event['event_properties.error_context'] = 'user_session';
    }


    return event;
  });
}

Related topics

  • Web request performance—HTTP event modifiers.
  • Error and crash reporting—exception events.
  • Configuration—agent configuration.
Related tags
Digital Experience