Custom events

  • Latest Dynatrace
  • How-to guide
  • 1-min read
  • Published Dec 24, 2025

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.

Session properties

Configure event and session properties

Before you can send event or session properties from your application, you must first define them in the Dynatrace web UI. Any properties that are not pre-configured will be discarded.

To define a new property:

  1. In Experience Vitals Experience Vitals, select the frontend for which you want to add the property.
  2. Select the Settings tab, then choose Event and session properties.
  3. Select Add under either Defined event properties or Defined session properties, depending on the type of property you want to create.
  4. In the Field name box, enter a name for your property (for example, cart.total_value).
  5. Optional To make the field name case-insensitive, turn on Field name validation should be case-insensitive.
  6. From the Datatype list, select the appropriate data type for your property: string, boolean, or number.

Dynatrace automatically prefixes your field name with event_properties. or session_properties. based on the property type you selected. For example, a field name of cart.total_value will become event_properties.cart.total_value.

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

  • Keys must be prefixed with event_properties..
  • Field names must contain only alphanumeric characters, underscores, and dots.
  • Each dot must be followed by an alphabetic character.
  • Each underscore must be followed by an alphabetic character or number.
  • Values must be primitive types (String, num, bool).

Valid examples:

  • event_properties.checkout_step
  • event_properties.cart.total_value
  • event_properties.user_tier

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);

Limits

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

  • Naming:
    • Field name maximum length: 100 characters (including the event_properties. / session_properties. prefix).
    • Allowed characters in field name: A–Z, a–z, 0–9, underscore _, and dot ..
  • Counts—a maximum of 50 event and session properties can be configured.
  • Values—for event and session properties of data type string, the length is limited to 5000 characters.

Modifiable fields

The following fields can be modified:

  • event_properties.* - Custom event properties
  • session_properties.* - Session properties (only on session property events)
  • url.full - The complete request URL
  • exception.stack_trace - Exception stack traces

Read-only fields

Most standard Dynatrace fields cannot be modified, including:

  • start_time.
  • http.*.
  • characteristics.*.
  • All system-generated metadata.

Attempting to modify read-only fields will have no effect. The original values will be preserved.

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;
  });
}

Important considerations

  • Execution order—modifiers run in the order they were added.
  • Returning null—discards the event; subsequent modifiers won't run.
  • Performance—keep modifiers efficient—they run for every event.
  • Primitive values—event properties can only contain primitive types (string, num, bool).
  • Error handling—exceptions in modifiers are logged but don't block other modifiers.
Related tags
Digital Experience