Importing metric events

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.

API details

Here's how to structure your import metric request:

Request body format

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

[
  {
    "kind": "custom",
    "key": "your-event-key",
    "creationDate": 16420388151234,
    "metricValue": 32.0,
    "contextKeys": {
      "user": "context-key-123abc"
    }
  }
  // ... more events
]
COPY

Here are the details of each custom event field:

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.

curl -i -X POST \
  -H 'Authorization: YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Content-Length: 282' \
  -H 'X-LaunchDarkly-Event-Schema: 4' \
  -H 'User-Agent: MetricImport-ACME-CORPORATION-int/1.0' \
  -d '[{"kind":"custom","contextKeys":{"user":"context-key-123abc"},"creationDate":1638561938594,"key":"example-metric-123abc","metricValue": 11.0},{"kind":"custom","contextKeys":{"user":"context-key-456def"},"creationDate":1638561938594,"key":"example-metric-456def","metricValue": 6.0}]' \
  https://events.launchdarkly.com/v2/event-data-import/example-project-key/example-environment-key
COPY

Responses and error handling

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.

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.