Filtering custom metric events

This topic explains how to use filters to include only specific custom events in a metric, based on context attributes or event properties.

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.

A second metric using the same event key, filtered to include only events where productCategory is gizmo.

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

You can only apply filters to custom metrics. Metrics based on clicked or tapped events and page view events do not support filtering.

If you use a filtered metric in a LaunchDarkly experiment, LaunchDarkly will not apply CUPED to the experiment results.

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 attribute, such as “country”, “plan”, or “deviceType”
• Event property, 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.

Filters do not evaluate nested data or arrays. If your event includes nested objects or arrays, LaunchDarkly ignores those fields when applying metric 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.

A metric definition that includes only events from contexts of kind user where the country is CA and the productCategory event property equals widget.

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:

JavaScript

    track("purchaseCompleted", {
      productCategory: "widget",
      currency: "USD"
    })

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 a data warehouse. If you are not using an external warehouse, leave the selection on LaunchDarkly hosted.

4. Select the Custom event kind.

5. Search for or enter an Event key.

The Create metric panel, with Custom event kind selected and event key entered.

6. Click Filter event by.

7. Select Context attribute or Event property.

8. Define your filter condition:

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

A metric definition that includes only events from the user context kind where the country attribute is set to CA.

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

A filter that includes only events where the productCategory event property is set to widget.

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

A metric definition that includes only events from contexts of kind `user` where the `plan` is `enterprise` or the `country` is `CA`, and the `productCategory` event property is `widget`.

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

11. Click Create metric.

No changes are required to your SDK event tracking: LaunchDarkly applies the filters automatically when processing metric events. You do not need to change how the event is tracked in your SDK.

However, you must be using an SDK that supports inline contexts, which is a format for how the SDK sends custom event information to LaunchDarkly. To confirm that your SDK supports this, read Supported features. Find your SDK and look for the “Inline contexts in custom events” in the corresponding table.