Try it free

Custom events

  • Latest Dynatrace
  • How-to guide

Dynatrace supports custom events to track user interactions, business metrics, and application-specific signals. Events can also be enriched before they are sent by applying 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

Custom events are reported using Dynatrace.sendEvent(...) with optional duration and event properties.

Consider basic usage

// Simple event
Dynatrace.sendEvent(EventData())


// Event with duration (in milliseconds)
Dynatrace.sendEvent(EventData().withDuration(150))
// Simple event
Dynatrace.sendEvent(new EventData());


// Event with duration (in milliseconds)
Dynatrace.sendEvent(new EventData().withDuration(150));

Add event properties

Custom properties provide context for reported events. Property keys must be prefixed with event_properties..

Dynatrace.sendEvent(
    EventData()
        .withDuration(250)
        .addEventProperty("event_properties.checkout_step", "payment_confirmed")
        .addEventProperty("event_properties.cart_value", 149.99)
        .addEventProperty("event_properties.item_count", 3)
)
Dynatrace.sendEvent(new EventData()
    .withDuration(250)
    .addEventProperty("event_properties.checkout_step", "payment_confirmed")
    .addEventProperty("event_properties.cart_value", 149.99)
    .addEventProperty("event_properties.item_count", 3)
);

Property naming rules

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

Event modifiers

Event modifiers intercept events before they are sent. They can be used to add common properties, redact sensitive information, or filter events.

On Android, modifiers operate on a JSONObject representation of the event.

Add an event modifier

val modifier = EventModifier { event ->
    // Add build variant context to all events
    event.put("event_properties.build_type", BuildConfig.BUILD_TYPE)
    event.put("event_properties.flavor", BuildConfig.FLAVOR)
    event
}


Dynatrace.addEventModifier(modifier)
EventModifier modifier = (JSONObject event) -> {
    // Add build variant context to all events
    event.put("event_properties.build_type", BuildConfig.BUILD_TYPE);
    event.put("event_properties.flavor", BuildConfig.FLAVOR);
    return event;
};


Dynatrace.addEventModifier(modifier);

Filter events

Returning null discards an event.

val modifier = EventModifier { event ->
    // Events happening on the com.example.MainActivity activity will be dropped.
    if (event.optString("view.detected_name") == "com.example.MainActivity") {
        return@EventModifier null
    }
    event
}


Dynatrace.addEventModifier(modifier)
EventModifier modifier = (JSONObject event) -> {
    // Events happening on the com.example.MainActivity activity will be dropped.
    if ("com.example.MainActivity".equals(event.optString("view.detected_name"))) {
        return null;
    }
    return event;
};


Dynatrace.addEventModifier(modifier);

Redact sensitive data

val modifier = EventModifier { event ->
    // Redact user IDs from URLs
    val url = event.optString("url.full", null)
    if (url != null) {
        val redactedUrl = url.replace(Regex("/users/\\w+/"), "/users/{id}/")
        event.put("url.full", redactedUrl)
    }
    event
}


Dynatrace.addEventModifier(modifier)
EventModifier modifier = (JSONObject event) -> {
    // Redact user IDs from URLs
    String url = event.optString("url.full", null);
    if (url != null) {
        String redactedUrl = Pattern.compile("/users/\\\\w+/")
            .matcher(url)
            .replaceAll("/users/{id}/");
        event.put("url.full", redactedUrl);
    }
    return event;
};


Dynatrace.addEventModifier(modifier);

Remove event modifiers

// Store the modifier when adding it
val modifier = EventModifier { event ->
    event.put("event_properties.custom", "value")
    event
}


Dynatrace.addEventModifier(modifier)


// Remove when no longer needed
Dynatrace.removeEventModifier(modifier)
// Store the modifier when adding it
EventModifier modifier = (JSONObject event) -> {
    event.put("event_properties.custom", "value");
    return event;
};


Dynatrace.addEventModifier(modifier);


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

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 example

Conditional event enrichment (example)

The following example shows how to enrich only specific event types. It adds context to HTTP events (for API segmentation) and to error events (for faster triage).

fun setupConditionalEnrichment(apiClientName: String) {
    val modifier = EventModifier { event ->
        // Add context only for HTTP events
        if (event.optBoolean("characteristics.has_request")) {
            event.put("event_properties.api_client", apiClientName)
            event.put("event_properties.api_kind", "backend")
        }


        // Add context only for error events
        if (event.optBoolean("characteristics.has_error")) {
            event.put("event_properties.triage_owner", "mobile")
            event.put("event_properties.triage_severity", "error")
        }


        event
    }


    Dynatrace.addEventModifier(modifier)
}
public void setupConditionalEnrichment(final String apiClientName) {
    EventModifier modifier = (JSONObject event) -> {
        // Add context only for HTTP events
        if (event.optBoolean("characteristics.has_request")) {
            event.put("event_properties.api_client", apiClientName);
            event.put("event_properties.api_kind", "backend");
        }


        // Add context only for error events
        if (event.optBoolean("characteristics.has_error")) {
            event.put("event_properties.triage_owner", "mobile");
            event.put("event_properties.triage_severity", "error");
        }


        return event;
    };


    Dynatrace.addEventModifier(modifier);
}

Related topics

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