Custom events

  • Latest Dynatrace
  • Explanation
  • 1-min read
  • Published Jan 12, 2026

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 must be configured before they can be used. Incoming event and session properties that are not configured are dropped during event ingest. Read more about configuring custom events and session properties.

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

  • 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, int, 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

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

Limits

  • 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.

Modifier limitations

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

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.request.method
  • http.response.status_code
  • span.id
  • trace.id
  • All system-generated metadata

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

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

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, int, bool).
  • Error handling—exceptions in modifiers are logged but don't block other modifiers.
Related tags
Digital Experience