Creating metrics from traces

This topic explains how to create LaunchDarkly custom metrics from OpenTelemetry traces.

LaunchDarkly lets you create custom metrics from OpenTelemetry traces instrumented in your code, for use with guarded rollouts.

Creating metrics from traces lets you use existing OpenTelemetry instrumentation to measure how application behavior changes during a guarded rollout, without re-instrumenting those behaviors as metric events using the track() method. You define a query that selects the trace spans you want to use to measure your application, and create a metric based on the query result. Each matching span observed during a guarded rollout indicates a metric event.

To create numeric metrics from traces, such as for measuring regressions, you specify the span attribute name that provides the value you want to monitor.

Trace metrics use the same aggregation and analysis methods as LaunchDarkly metrics created from metric events. To learn more, read Components of a metric.

Prerequisites and limitations

You can create custom metrics from trace spans that include a LaunchDarkly feature flag span event, indicated by the feature_flag.set.id attribute. The LaunchDarkly observability SDK plugins automatically include feature flag span events when you create trace spans.

If your application uses a different OpenTelemetry library or package, you can configure the OpenTelemetry collector or use tracing hooks to add the required feature flag span events. To learn more, read Server-side SDKs.

Trace metrics are compatible with guarded rollouts for managing feature releases. You cannot use trace metrics with LaunchDarkly experiments.

Creating trace metrics

You can create trace metrics using either the LaunchDarkly “Create metric” dialog or the observability “Traces” page. Both methods let you create a span query to select the spans you want to monitor in the metric.

Use the “Create metric” dialog if you are familiar with creating metrics and filtering metric events and you want to use a similar interface to create metrics from spans. Use the “Traces” page if you are familiar with the observability search syntax or you want a real-time preview of your filter query results.

Using the Create metric interface

To use the “Create metric” dialog to create a new trace metric:

1. Navigate to the Metrics list.

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

3. Select Traces from the “Event source” drop-down.

4. Use the “Filter to spans” field to create a query that selects the trace spans to use for the new metric.

   

   The “Filter to spans” field uses these basic controls:

   • Click an empty spot in the field to display the span attributes, operators, or relational functions you can add to the query at that spot.
   • Type characters to filter the available selections you can add. Enter or click a name in the drop-down list to add the value.
   • Use checkboxes in the drop-down list to select multiple values, or use commas to separate multiple, typed values.
   • Click an existing attribute name, value, or operator to change or edit the displayed value.
   • Click the x icon next to a name, value, or operator to delete it.

   Span functions (Any span, Any span 2, Any span 3) can only be added to the top level of the filter query, and cannot be nested within parentheses. To learn more, read Span functions for trace search.

5. (Optional.) Click View traces to view recent spans that match your filter query. This opens a new tab to the Traces page with your filter query applied.

6. Select a measurement method.

   • Use Count or Occurrence to measure matching trace spans during a guarded rollout.
   • Use Value/size to create a numeric metric that aggregates a value from the filtered trace spans.

7. If you are configuring a numeric metric:

   1. Click the “Choose a numeric span attribute” field and type or select the span attribute that provides the numeric value you want to measure.
   2. Select Include units and set the value to 0 or Exclude units that generate no events to choose how to handle units that do not generate a matching span during a rollout.
   3. Enter a Unit of measure to describe the value you are measuring.

8. Use the “Metric definition” section to configure the metric’s analysis method. To learn more, read Analysis method.

9. Enter a Metric Name.

10. (Optional) Add a Description.

11. (Optional) Add any Tags.

12. (Optional) Update the Maintainer.

13. Click Create metric.

Using the Traces interface

To use the “Traces” page to create a new trace metric:

1. Navigate to the Traces page.
2. Use the Search… field to create a query that selects the trace spans to use for the new metric. Use feature_flag.set.id EXISTS to limit results to trace spans that have the required feature flag span event. To learn more, read Search specification.
3. View the results in the “Spans” list to preview your filter query.
4. Click Create metric to create a metric using the current filter query. This opens the Create metric dialog and populates it with the query you created.
5. Select a measurement method.
   • Use Count or Occurrence to measure matching trace spans during a guarded rollout.
   • Use Value/size to create a numeric metric that aggregates a value from the filtered trace spans.
6. (Optional.) If you are configuring a numeric metric, click the “Choose a numeric span attribute” field and type or select the span attribute that provides the numeric value you want to measure.
7. If you are configuring a numeric metric:
   1. Click the “Choose a numeric span attribute” field and type or select the span attribute that provides the numeric value you want to measure.
   2. Select Include units and set the value to 0 or Exclude units that generate no events to choose how to handle units that do not generate a matching span during a rollout.
   3. Enter a Unit of measure to describe the value you are measuring.
8. Use the “Metric definition” section to configure the metric’s analysis method. To learn more, read Analysis method.
9. Enter a Metric Name.
10. (Optional) Add a Description.
11. (Optional) Add any Tags.
12. (Optional) Update the Maintainer.
13. Click Create metric.

Adding trace metrics to guarded rollouts

You select trace metrics for use with guarded rollouts in the same way you select other LaunchDarkly metrics. To learn more, read Creating guarded rollouts.