Custom numeric metrics

This topic explains how to create a custom numeric metric in LaunchDarkly.

Overview

This topic explains how to create a custom numeric metric in LaunchDarkly. Custom numeric metrics track changes to the amount of something, such as dollars spent or latency time. Unlike conversion metrics, which track how many users triggered an event or the number of times an event occurs, numeric metrics let you measure changes in value against a baseline flag variation you choose.

For example, you can use numeric metrics to track:

• Page load time
• The number of items in a shopping cart at checkout
• How long it takes for a server to respond to a request

SDKs send events at regular intervals, such as every five seconds. If a browser redirects an end user to another page, any events that occurred between when the SDK last sent events and when the browser redirected will be lost. To avoid this, call track and then flush when you know the browser will redirect an end user to another page, such as on click. To learn more, read Sending custom events and Flushing events.

Metric definition

When you create a custom numeric metric, you must first decide:

• What you want to measure: select Value/size.
• Under “Choose how multiple event values are aggregated per unit,” select:
  • Sum: the total value per unit. For example, this option adds together the total purchase amount of all of a customer’s purchases.
  • Average: the average value per unit. For example, this option takes the average purchase price of all of a customer’s purchases.

Then, custom numeric metric definition options include:

• Analysis method:
  • Average: “average” is the default analysis method. For metrics you plan to use in funnel metric groups, you must select “Average.”
  • P50 to P99: for percentile analysis you can choose between P50-P99, which represent the 50th through the 99th percentile.
• [analysis unit]: one or more context kinds, such as “user,” “device,” or “request,” that the metric can measure events from.
• Success criteria:
  • higher is better: choose this option for metrics measuring positive things like cart checkouts or sign-ups.
  • lower is better: choose this option for metrics measuring negative things like errors.
• Units without events:
  • Exclude units that generate no events: this option is best for latency metrics. If LaunchDarkly never receives an event for a context instance, you do not want to default to 0 because LaunchDarkly would interpret this as an extremely fast latency time, which would skew or invalidate the results.
  • Include units and set the value to 0: this option is best for metrics where an incomplete process can be treated the same as 0, such as tracking cart totals for an online store. In this example, customers who put items in their cart but never completed the checkout process are treated as if they purchased $0.
• Unit of measure: the label for what the metric is measuring, such as dollars or milliseconds.

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

You cannot use custom numeric metrics in funnel metric groups. To learn more, read Funnel metric groups.

Create custom numeric metrics

To add a custom numeric metric in LaunchDarkly, you must identify it with a code snippet embedded in your app.

This is an example of sending a custom event:

Example event

    client.track("Example event key", context, null, numericValue);

    /* The `context` parameter is omitted in client-side SDKs */

Numeric metrics require an event key from your application’s code to track metric data. The area of your code you should put custom metric information into, and the type of information you should include, vary based on which SDKs you use.

Usually, the information you should put in your code includes the event key, context object, data field, or numeric value fields.

Sending custom events to LaunchDarkly requires a unique event key. You can set the event key to anything you want. Adding this event key to your codebase lets your SDK track actions customers take in your app as events. To learn more, read Sending custom events.

LaunchDarkly also automatically generates a metric key when you create a metric. You only use the metric key to identify the metric in API calls. To learn more, read Creating and managing metrics.

Try it in your SDK: Sending custom events

To create a custom numeric metric:

1. Navigate to the Metrics list.

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

3. If you use Snowflake native Experimentation, you have the option to select either LaunchDarkly hosted or Warehouse native.

   • Select LaunchDarkly hosted to measure events from LaunchDarkly SDKs.
   • Select Warehouse native to measure events from an external warehouse, such as Snowflake.
     • Select an existing Metric data source or click + Create to create a new data source. To learn more, read Metric data sources.

4. If you chose the LaunchDarkly hosted event source, select an event kind of Custom.

5. Search for or enter an Event key.

   • A list of events your environment has recently received appears when you click into the Event key field. Begin typing an event key to view a list of events that match your search. Hover on an event from the list to view which environments the event appears in, which context kinds sent the latest event, and which SDKs the event is coming from.

6. Choose Value/size as what you want to measure.

7. Choose how multiple event values are aggregated per unit:

   • Sum: the total value per unit.
   • Average: the average value per unit.

8. In the Metric definition section, select the following:

   • Average or a specific percentile click rate. Warehouse native metrics use only the Average analysis method.
   • of the per [analysis unit] event: select the context kind for the metric to measure events from.
   • where higher is better or lower is better: select whether the desired outcome is a higher number or a lower number.

9. For metrics that use the Average analysis method, select an option to handle units without events:

   • Include units and set the value to 0: Select this option for metrics where an incomplete process can be treated the same as 0, such as for tracking cart totals for an online store.
   • Exclude units that generate no events: Select this option for latency metrics or other metrics where a default value of 0 would skew or invalidate results.

10. Enter a Unit of measure.

11. Enter a Metric Name.

12. (Optional) Add a Description.

13. (Optional) Add any Tags.

14. (Optional) Update the Maintainer.

15. Click Create metric.

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

You can also use the REST API: Create metric