Count distinct metrics

This topic explains how to create a count distinct metric in LaunchDarkly. A count distinct metric measures the number of unique values that appear in a warehouse column you choose.

About count distinct metrics

A count distinct metric aggregates the count of unique values in a warehouse column for each analysis unit, then uses mean or percentile analysis for that aggregation across the flag variations in a connected experiment. LaunchDarkly ignores duplicate and null values in the column.

Use a count distinct metric when you want to measure a distinct signal independently of how many total metric events a unit generates. For example, you can use count distinct metrics to measure:

• The number of distinct products a customer views per session
• The number of distinct orders a customer places
• The number of distinct sessions a user starts

Because each unit’s distinct count is a number, LaunchDarkly analyzes count distinct metrics as numeric metrics. The Metrics list identifies them with their own metric kind, “Count distinct.”

Ratio metrics also support the count distinct aggregation for their numerator and denominator components. To learn more, read Aggregation types for ratio metrics.

Example metric in SQL

Some customers find it helpful to think about LaunchDarkly metric calculations in terms of SQL statements. This example shows how a count distinct metric could be represented as a SQL expression, using example table and column names to represent metric components:

1
WITH unit_aggregates AS (
2
   SELECT user_id, COUNT(DISTINCT order_id) AS distinct_count
3
   FROM events
4
   GROUP BY user_id
5
)
6
SELECT AVG(distinct_count)
7
FROM unit_aggregates;

In this example:

• events is a warehouse table that stores all of the metric events on which the metric is defined.
• order_id is the warehouse column you select in the “Count distinct on” menu. COUNT(DISTINCT order_id) counts the unique values in that column for each unit, ignoring duplicates and nulls.
• user_id is a table column that represents the context both for the metric analysis unit and for the randomization unit used in the connected experiment. This example uses the “user” context kind, but a metric can use other context kinds, such as “account,” “session,” or “device.”
• AVG represents the aggregation function that corresponds to the analysis method you select. Average analysis uses AVG, and percentile analysis uses PERCENTILE_CONT.

Prerequisites

To create a count distinct metric, you need:

• A configured warehouse integration and a metric data source. To learn more, read Metric data sources.
• Column mappings on that data source that include the column you want to use for counting unique values. The “Count distinct on” menu lists only those columns that are mapped in the selected data source.

Metric definition

When you configure the metric definition for a count distinct metric, you first select Count distinct as the aggregation type. You then select the warehouse column to count unique values in. The completed definition reads as a sentence:

Count distinct of <column> per <analysis units>, then compute the <analysis method> of those counts where <success criteria>

Count distinct metric definition options include:

• The warehouse column to count unique values in. This option is required.
• The analysis units to use for measuring the event. This can be one or more context kinds, such as “user,” “device,” or “request,” that the metric can measure events from.
• Analysis method:
  • Average: “average” is the default analysis method. This method calculates the average of the per-unit distinct counts.
  • P50 to P99: To use percentile analysis, choose between P50-P99. The options represent the 50th through the 99th percentile. This method analyzes the per-unit distinct counts that fall into the chosen percentile.
• Success criteria:
  • higher is better: Choose this option for metrics measuring positive things like distinct products purchased.
  • lower is better: Choose this option for metrics measuring negative things like distinct error types encountered.

To learn more about the metric definition options, read Metric components.

Limitations

Count distinct metrics do not support all of the options available to other numeric metrics. Consider these limitations before you create one:

• You cannot configure winsorization for a count distinct metric. If you switch an existing aggregation to Count distinct, LaunchDarkly clears any winsorization options you configured.
• You cannot choose how to handle analysis units that do not generate events. LaunchDarkly always includes units that generate no events and assigns them a distinct count of zero. To learn more, read Units without events.
• You cannot use count distinct metrics in funnel metric groups, because LaunchDarkly analyzes them as numeric metrics. To learn more, read Funnel metric groups.

Create a count distinct metric

To create a count distinct metric:

1. Open the Data section and navigate to the Metrics list.
2. Click Create metric. The “Create metric” dialog appears.
3. Select Warehouse native from the “Event source” menu.
4. Select an existing Metric data source, or click + Create to create a new data source. To learn more, read Metric data sources.
5. Search for or enter an Event key.
6. Choose Count distinct from the menu in the Metric definition section. The window populates a full metric definition using default values.
7. Use the “Count distinct on” menu to choose the warehouse column to use for counting unique values. This menu lists the columns mapped in the warehouse data source you selected.
8. Change options in the “Metric definition” menus as needed:
   • Change or select additional context kinds to use as the analysis units for the metric. Only context kinds marked as available for experiments and guarded rollouts appear as options. To learn more, read Mark context kinds available for experiments.
   • Select Average or a percentile between P50 to P99 to configure the analysis method.
   • Choose higher is better or lower is better to define success criteria for attached experiments.
9. (Optional) Choose Enable custom measurement window to configure a metric measurement window. To learn more, read Metric measurement window.
10. Enter a Metric name.
11. (Optional) Add a Description.
12. (Optional) Add any Tags.
13. (Optional) Update the Maintainer.
14. Click Create.

You can connect the metric to an experiment to monitor the impact of a flag change.

You can also use the REST API: Create metric