Custom events

Latest Dynatrace
Explanation
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

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

In Experience Vitals, select the frontend for which you want to add the property.
Select the Settings tab, then choose Event and session properties.
Select Add under either Defined event properties or Defined session properties, depending on the type of property you want to create.
In the Field name box, enter a name for your property (for example, cart.total_value).
Optional To make the field name case-insensitive, turn on Field name validation should be case-insensitive.
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..

using Dynatrace.MAUI;

double value = 149.99;

var event = new EventData()
  .AddEventProperty("event_properties.checkout_step": "payment_confirmed")
  .AddEventProperty("event_properties.cart_value", value)
  .AddEventProperty("event_properties.item_count", 3);

Agent.Instance.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

using Dynatrace.MAUI;

class MyModifier : IEventModifier
{
  public Dictionary<string, object>? ModifyEvent(Dictionary<string, object> fields)
  {
    // Add custom fields to production events
    fields["event_properties.app_build"] = "1.2.3";
    fields["event_properties.environment"] = "production";
    return fields;
  }
}

...

Agent.Instance.AddEventModifier(new MyModifier(event));

Filter events

Return null to discard an event:

using Dynatrace.MAUI;

class MyModifier : IEventModifier
{
  public Dictionary<string, object>? ModifyEvent(Dictionary<string, object> fields)
  {
    // Discard events from test users
    if (fields["event_properties.is_test_user"] == true)
    {
      return null; // Discard event
    }

    return fields;
  }
}

...

Agent.Instance.AddEventModifier(new MyModifier(event));

Redact sensitive data

using Dynatrace.MAUI;

class MyModifier : IEventModifier
{
  public Dictionary<string, object>? ModifyEvent(Dictionary<string, object> fields)
  {
    // Redact email addresses from custom properties
    if (fields.ContainsKey("event_properties.user_email"))
    {
      fields["event_properties.user_email"] = "[REDACTED]";
    }

    return fields;
  }
}

...

Agent.Instance.AddEventModifier(new MyModifier(event));

Remove event modifiers

using Dynatrace.MAUI;

// Remove the modifier when no longer needed
Agent.Instance.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

Add feature flags

using Dynatrace.MAUI;

class FeatureFlagModifier : IEventModifier
{
  var featureFlags = new Dictionary<string, object>
  {
    { "checkout_v2", true },
    { "new_payment_flow", false },
    { "enhanced_search", true }
  }

  public Dictionary<string, object>? ModifyEvent(Dictionary<string, object> fields)
  {
    foreach (var entry in fields)
    {
      fields[$"event_properties.ff_{entry.Key}"] = entry.Value;
    }
    return fields;
  }
}

...

Agent.Instance.AddEventModifier(new FeatureFlagModifier(event));

Conditional event enrichment

using Dynatrace.MAUI;

class EnrichmentModifier : IEventModifier
{
  public Dictionary<string, object>? ModifyEvent(Dictionary<string, object> fields)
  {
    // Add experiment tracking to checkout events
    if (fields.ContainsKey("event_properties.checkout_step"))
    {
      fields["event_properties.experiment_id"] = "checkout_flow_v2";
      fields["event_properties.variant"] = "treatment_a";
    }

    return fields;
  }
}

...

Agent.Instance.AddEventModifier(new EnrichmentModifier(event));

Web request performance—HTTP event modifiers.
Error and crash reporting—exception events.
Configuration—agent configuration.