Filtering custom metric events

Overview

This topic explains how to use filters to include only specific custom events in a metric, based on context attributes or event properties. You can create and apply filters directly in the LaunchDarkly user interface (UI) without changing your event instrumentation.

Instead of sending different events for each value of a context attribute or event property, you can send a single custom event and define multiple metrics from it by applying filters.

For example, if you send a purchaseCompleted event with a productCategory property, you can define one metric that includes only purchases of widgets and another that includes only purchases of gizmos. You do not need to change your instrumentation or send separate events.

LaunchDarkly applies a metric’s filter when it processes events during a guarded release or experiment. Only events that match the event key and satisfy the filter are included in the metric.

Benefits of filters

Metric filters help you:

• Define metrics for specific values of context attributes or event properties using data you already send. For example, you can define a metric to measure purchaseCompleted events for users where plan = "enterprise" or country = "CA".
• Use a single custom event to create multiple metrics, without complicating your instrumentation.
• Change what a metric measures directly in the LaunchDarkly UI, without updating your code or redeploying.
• Reuse filtered metrics across multiple guarded rollouts and experiments.

Filter options

You can filter custom metrics using two types of data:

• Context attributes, such as country, plan, or deviceType
• Event properties, such as productCategory, currency, or pageType

Filters only match top-level key-value pairs in the data object of a custom event. Supported values include strings, numbers, and true or false values.

You can combine multiple filters using either AND or OR. To use both, add sub-filters.

Example: Users in Canada who made a purchase

To include only events from users in Canada who purchased a widget:

• Context attribute: user.country = "CA"
• Event property: productCategory = "widget"

You can define one metric that includes only events matching both filters.

Filter evaluation

LaunchDarkly evaluates metric filters when the event is received. Filters determine whether a specific event is included in the metric calculation. Filters do not affect flag targeting, flag evaluations, or exposure logic.

Context attribute filters

Context attribute filters match data from the context that triggered the event. These filters are evaluated at the time the event is received.

Event property filters

Event property filters match key-value pairs in the data field of a custom event. These filters only work if the event data is a flat JSON object that includes string, number, or boolean values.

Here is an example of a track() call in JavaScript:

1
track("purchaseCompleted", {
2
  productCategory: "widget",
3
  currency: "USD"
4
})

In this example, productCategory and currency can both be used in metric filters.

Add a filter to a custom metric

You can add metric filters when you create a new custom metric or edit an existing one. Filters are available in the LaunchDarkly UI during metric definition.

To create a new metric with filters:

1. Navigate to the Metrics list.

2. Click Create metric. The “Create metric” panel appears.

3. Select the Custom event kind.

4. Search for or enter an Event key.

   

5. Click Filter event by.

6. Select Context attribute or Event property.

7. Define your filter condition:

   • For Context attribute, select the context kind, context attribute, and filter operator:

     

   • For Event property, select the event property, value, and filter operator:

     

8. (Optional) Click Add filter or Add another filter to extend your filtering logic.

   

9. Continue creating your metric according to the create procedure for the custom metric.

10. Click Create metric.