This topic explains how to import metric events from your existing data pipeline for use with Experimentation and guarded rollouts. Using the metric import REST API described below, you can send your already-instrumented metrics into LaunchDarkly without writing and deploying new code for each metric.
Events are specific to one LaunchDarkly environment.
If the metric events you want to use are already flowing through a tool such as Census, Sentry, Snowplow, Tealium, or Twilio Segment, consider using one of LaunchDarkly’s Experimentation and metric integrations.
You can import metric events from both client-side and server-side applications.
You can use this endpoint to send client-side custom events to LaunchDarkly when you cannot initialize the SDK. You can also use other tools, such as Shopify’s Liquid framework with Custom and Web Pixels, to subscribe and send events.
Here’s how to structure your import metric request for client-side applications:
Here’s how to structure your import metric request for server-side applications:
The request body must consist of a JSON array of custom events. Each event can include the following fields.
The data object is optional and can contain additional attributes such as error codes, request details, or other metadata.
Here are the details of each custom event field:
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.
Here is an example curl invocation for client-side applications that sends two metric events for different contexts to the same metric:
Here is an example curl invocation for server-side applications that sends two metric events for different contexts to the same metric:
Clients should expect to receive the following response status codes from the API:
4xx error responses have bodies in JSON format describing the reason for the error.
5xx error responses should be rare, and indicate the metrics may not have been accepted for import. To learn more, read Retry failed requests.
There are a few known limitations with the metric import API. These include the following:
custom. If this validation fails, the API returns a 400 error response.events.launchdarkly.com must be during an experiment’s running iteration, and must be after the time the contexts included in contextKeys first encountered the experiment. This means it is not possible to import events for an experiment iteration that you have already stopped.We recommend the following best practices when importing metric events.
If possible, for efficiency, clients should send batches of events in each request, rather than making a separate request per event. For example, consider time-based batches sent once per minute. Clients are free to choose their own batch size, but the request body must be smaller than 10MB in total.
Clients should not retry requests receiving 4xx responses, with the exception of 429 Too Many Requests.
429 and 5xx responses indicate transient issues, so it is appropriate to retry requests receiving these responses, in order to ensure that their events are accepted for import. Clients that retry requests must follow these instructions when doing so:
X-LaunchDarkly-Payload-ID header. This header must contain a freshly generated payload id for each request. However, when retrying, the retries must reuse the same payload id as the original request. LaunchDarkly uses this header to deduplicate repeated requests and ensure events are only processed once.There is no separate charge for importing metric events. However, if you use Data Export, imported events will be included in the data export, and will count toward Data Export usage. To learn more, read Data Export.