Importing events

This topic explains how to import metric events from your existing data pipeline for use with Experimentation and guarded rollouts.

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.

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.

API details

You can import metric events from both client-side and server-side applications.

Client-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:

| Request element

Description

| --- | | Base URL

| https://events.launchdarkly.com | | Base URL

| https://events.launchdarkly.us | | Base URL

| https://events.eu.launchdarkly.com | | Resource

| /events/bulk/YOUR_CLIENT-SIDE_ID

The client-side event endpoint uses the client-side ID within the URL to identify the environment to submit events for. Replace YOUR_CLIENT-SIDE_ID with the client-side ID for your environment. You can find the client-side ID in the SDK key dialog. | | REST method

| POST | | Headers

|

| The events to import, represented as a JSON array. For details on the format, read Request body format , below. |

Server-side applications

Here’s how to structure your import metric request for server-side applications:

| Request element

Description

| --- | | Base URL

| https://events.launchdarkly.com | | Base URL

| https://events.launchdarkly.us | | Base URL

| https://events.eu.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

|

| The events to import, represented as a JSON array. For details on the format, read Request body format , below. |

Request body format

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.

Array of custom events

    [
      {
        "kind": "custom",
        "key": "example-event-key",
        "creationDate": 16420388151234,
        "metricValue": 32.0,
        "contextKeys": {
          "user": "example-context-key"
        },
        "data": {
          "error": "xyz",
          "screen": "checkout"
        }
      }
      // ... more events
    ]

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 ignores 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”: “example-user-key”.

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

| The data object is optional and can contain additional attributes such as error codes, request details, or other metadata. |

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.

Examples

Here is an example curl invocation for client-side applications that sends two metric events for different contexts to the same metric:

Example curl for client-side applications

    curl -i -X POST \
      -H 'Content-Type: application/json' \
      -H 'X-LaunchDarkly-Event-Schema: 4' \
      -d '[{"kind":"custom","contextKeys":{"user":"example-context-key-1"},"creationDate":1638561938594,"key":"example-metric-key-1","metricValue": 11.0},{"kind":"custom","contextKeys":{"user":"example-context-key-2"},"creationDate":1638561938594,"key":"example-metric-key-2","metricValue": 6.0}]' \
      https://events.launchdarkly.com/events/bulk/example-client-side-id

Here is an example curl invocation for server-side applications that sends two metric events for different contexts to the same metric:

Example curl for server-side applications

    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":"example-context-key-1"},"creationDate":1638561938594,"key":"example-metric-key-1","metricValue": 11.0},{"kind":"custom","contextKeys":{"user":"example-context-key-2"},"creationDate":1638561938594,"key":"example-metric-2key-2","metricValue": 6.0}]' \
      https://events.launchdarkly.com/v2/event-data-import/example-project-key/example-environment-key

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