Importing metric events

Read time: 6 minutes

Last edited: Dec 02, 2024

Overview

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.

You may want to use a metric integration

If the metric events you want to use are already flowing through a tool such as Census, Sentry, Segment, Snowplow, or Tealium, consider using one of LaunchDarkly's Experimentation and metric integrations.

API details

Here's how to structure your import metric request:

Request element	Description
Base URL	`https://events.launchdarkly.com`
Resource	`/v2/event-data-import/YOUR_PROJECT_KEY/YOUR_ENVIRONMENT_KEY` Replace `YOUR_PROJECT_KEY` and `YOUR_ENVIRONMENT_KEY` with the project key and environment key, respectively, for the environment your metric events pertain to. To learn how to find these, read Project keys and Environment keys.
REST method	`POST`
Headers	`Authorization: YOUR_ACCESS_TOKEN`, required. This can be either a personal or service token. The access token must have a role that allows the `importEventData` action. We strongly recommend using an dedicated access token with this permission. To learn more, read Environment actions. `Content-Type: application/json`, required `Content-Length: LENGTH_IN_BYTES`, required `X-LaunchDarkly-Event-Schema: 4`, required `X-LaunchDarkly-Payload-ID: YOUR_PAYLOAD_ID`, optional. Use this to send a UUID for the payload, which you can use to retry failed requests. `User-Agent: MetricImport-YOUR_COMPANY_NAME-int/VERSION`, required. This helps us identify the source of traffic and debug issues. `VERSION` can be any format, but you should update it if you make major changes to your implementation. `Content-Encoding: gzip`, optional. If you compress your request body, you must include this header.
Request body	The events to import, represented as a JSON array.

Request body format

The request body must consist of a JSON array of custom events, which are JSON objects with the following shape:

Here are the details of each custom event field:

Custom event field	Description
`kind`	The event kind. A string, must be set to `custom`. To learn about other event kinds, read Event kinds.
`key`	The event key identifies your metric event. When you create your metric in LaunchDarkly, its Event key must exactly match this value. The event key is different than the metric key. To learn more, read Metrics.
`creationDate`	Timestamp of when the event is created, in Unix milliseconds.
`metricValue`	The numeric value of the metric. For numeric metrics, this is required. For conversion metrics, this is optional and LaunchDarkly will ignore it if provided.
`contextKeys`	A JSON object with one or more properties of the form <contextKind>: <contextKey>, listing the context keys for each context the metric event is associated with. For example, if your metric tracks user contexts, you might have `"user": "user-key-123abc"`. Each context kind and key must exactly match those for the corresponding context provided to any LaunchDarkly SDKs evaluating flags that will be used with the metric. To learn more about using context kinds in experiments, read Randomization units.

Event keys and metric keys are different

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.

Example

Here is an example curl invocation that sends two metric events for different contexts to the same metric. Replace client-side-id-123abc with your client-side ID.

Responses and error handling

Clients should expect to receive the following response status codes from the API:

Response status code	Description
202 Accepted	The request completed successfully and the metric events were accepted for import. Events may still not be recorded if their format does not conform to the required JSON schema. To learn more, read Known limitations.
400 Invalid Request	No data in the payload was accepted
401 Unauthorized	Your account does not have access to the metric import API, or your API access token does not have access to the importEventData action.
406 Not Acceptable	The `X-LaunchDarkly-Event-Schema` header is not set to `4`.
429 Too Many Requests	LaunchDarkly has recently received a very large volume of traffic from your account.
5xx	The metric import API is temporarily unavailable. In this case the metric events may not have been accepted for import.

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.

Known limitations

There are a few known limitations with the metric import API. These include the following:

There is a limit on the request body size of 10MB per request. If you need to batch-upload a large number of historical events, please contact us for more information.
The API performs minimal validation on request bodies:
- The API validates that the request is parsable JSON and that the event kind is custom. If this validation fails, the API returns a 400 error response.
- The API does not validate other fields. If there are other fields within the event that do not conform to the required JSON schema, the event may be accepted for import, but then not processed. The API returns a 202 response in this situation.
If you are using the metric import API with Experimentation, the time at which LaunchDarkly receives an event at 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.

Best practices

We recommend the following best practices when importing metric events.

Batch 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.

Retry failed requests

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:

Clients must not retry immediately, but must back off, preferably with an exponentially increasing delay.
To ensure events are only processed once when retrying, all requests must include the 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 will use this header to deduplicate repeated requests and ensure events are only processed once.

Billing implications

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.