Skip to main content

Documentation Index

Fetch the complete documentation index at: https://launchdarkly-preview.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This topic explains the schema of Data Export events. Data Export exposes the following kinds of events:
  • feature events
  • index events
  • identify events
  • click events
  • page view events
  • custom events
  • summary events. To export summary events, start a Support ticket.
  • debug events
LaunchDarkly no longer supports alias events for SDKs that support contexts. LaunchDarkly continues to support sending and receiving alias events for older SDK versions and for SDKs that do not yet support contexts. For a list of SDKs that still support alias events, read Aliasing users. Some Data Export destinations have different event formatting schema. If you use mParticle or Segment as your event destination, we have specific documentation for their event schema: These events are described in more detail below.

​
Event kinds

This table lists event kinds: | Description
Event kind
| --- | | feature | This event kind includes full-fidelity details of each individual feature flag evaluation. These events are present both for flags evaluated directly by a LaunchDarkly SDK, and for flags evaluated indirectly (for example, flags that are prerequisites of flags being evaluated directly). These events are only present if you explicitly enable detailed tracking for a feature flag, or if you are using an older SDK. | | index | This event kind contains the context attributes for a particular context, defined by a context key, when a feature flag evaluates the context. This event kind is not available for Twilio Segment or mParticle destinations. To export index events, start a Support ticket. | | identify | This event kind passes details about a context provided in an explicit identify call to the SDK. This event kind is not available for Twilio Segment or mParticle destinations. | | click | This event kind is generated by the LaunchDarkly SDK when an end user clicks on an HTML element matching a CSS selector configured on an experiment metric. | | page view | This event kind is generated by the LaunchDarkly SDK when an end user loads a page with URL matching a regular expression configured on an experiment metric. | | custom | This event kind is generated:
  • when your application calls any of the SDK’s track* methods
  • automatically when the SDK is initialized, when an error occurs, and when other web vitals occur, if you are using an observability SDK
| | summary | This event kind describes a roll-up of individual feature evaluations over an interval. These events are present both for flags evaluated directly by a LaunchDarkly SDK, and for flags evaluated indirectly (for example, flags that are prerequisites of flags being evaluated directly). To export summary events, start a Support ticket. | | debug | This event kind is similar to the feature event, except that it inlines the context value. This event kind is only sent if the debugEventsUntilDate attribute is set for a feature flag. |
The index and identify event kinds are not available for Twilio Segment and mParticle destinations.

​
SDK versioning for events

Newer SDKs generate the summary and index events described below. Older SDKs always send feature events regardless of whether detailed tracking is enabled for that flag. Newer SDKs send contextKeys and context as objects inside feature and custom events. Older SDKs send user or userKeys objects instead.
SDKs generate events using a schema versioned in the following way:
  • Events sent from SDKs upgraded for contexts are version 4.
  • Events sent from SDKs that only support users are version 3.
  • Events sent from supported versions of the PHP SDK, through version 6.0, are version 2. Events sent from the PHP SDK version 6.1 and later are version 4.
Each of these SDK event schemas are part of version 2 of the Data Export event schema. The definitions and examples on this page show the Data Export event schema version. If you are inspecting the events sent directly by your SDK, for example as part of debugging a Data Export integration, you may notice the SDK event versions.
To receive feature events, in addition to index, identify, and custom events, check the Send detailed events to data export destinations checkbox on a flag’s environment-specific settings page, or an environment’s Edit panel. By default, LaunchDarkly does not export summary events. To export summary events, start a Support ticket.

​
Event kind structures

LaunchDarkly sends each of these events as JSON files to your destinations. All events have the following top level structure: 
    {
      "project": "5744c96707c9900708000004",
      "environment": "578d1e02d2943862c52b9686",
      "event": {"id": "abc123xyz", ...},
      "version": 2,
    }
  • project: The ID of the LaunchDarkly project associated with the event.
  • environment: The ID of the LaunchDarkly environment associated with the event.
  • version: The Data Export event version.
  • event: The event itself. It is an object with a structure described below, depending on the kind of event.
    • id: Each event has a unique ID generated at export time. Due to Data Export’s delivery guarantee model it is possible for an event ID to be delivered more than once, so we do not recommend relying exclusively on these IDs for de-duplication.

​
Feature events

Feature events represent individual flag evaluations and are considered “full fidelity” events. Feature events are only sent by the SDK in one of these scenarios:
  • the trackEvents or trackEventsFallthrough attribute on the flag configuration is sent
  • the trackEvents attribute on a targeting rule is sent
  • the targeting rule or default rule when on has a rollout of kind "experiment" and the variation associated with the event is included in the tracked variations for that rollout
Here is an example feature event: 
    // this example is from Data Export event schema version 2
    {
        "kind": "feature",
        "id": "abc123xyz",
        "creationDate": 1462220944000,
        "contextKeys": {
          "user": "example-context-key"
        },
        "context": {
          "key": "example-context-key",
          "kind": "user",
          "name": "Sandy"
        },
        "key": "flag-key",
        "value": ["evaluation", "result"],
        "default": null,
        "version": 1,
        "variation": 0,
        "prereqOf": "upstream-key",
        "reason": {
            "kind": "RULE_MATCH",
            "ruleIndex": 0,
            "ruleId": "id",
            "inExperiment": true,
            "bigSegmentsStatus": "HEALTHY"
        },
        "samplingRatio": 10
    }
Here is a list of feature event properties:
  • kind: The kind for a feature event is feature. An SDK only generates a feature event if the you set the trackEvents attribute of the flag to true. You can also control this with settings in the UI.
  • creationDate: When the SDK requested the feature flag, as UNIX epoch time in milliseconds.
  • key: The key of the feature flag requested.
  • variation: The variation of the flag requested. The SDK stores flag variation values in an array. This value corresponds to the index of the variation the array. Boolean flags show as 0 or 1 for true and false. For other flags, the array index starts at 0 for the different variations.
  • variationName: The evaluated variation’s name, if it exists. If the evaluated variation doesn’t have a name, this field doesn’t appear.
  • value: The value of the feature flag returned by feature flag evaluation.
  • default: The default value that the application passed in.
  • version: The version of the evaluated feature flag.
  • reason: (Optional) Included only if the flag being evaluated was in an experiment and the target was part of the experiment allocation, or if you called a variation detail method.
    • Evaluations that were part of an experiment have the optional inExperiment attribute on the evaluation reason set to true. Evaluations that were not part of an experiment omit this attribute.
    • If you called a variation detail method, the reason property will be a JSON representation of the evaluation reason.
  • prereqOf: A feature flag key, if this flag evaluation was only performed in order to determine whether the prerequisite values were met for the indicated flag.
  • contextKeys: The keys of the context object used in a feature flag evaluation. SDKs periodically transmit details for the context object used in a feature flag evaluation as reported by the feature event with a separate index event.
  • context: The context object used in a feature flag evaluation.
  • userKey: The key of the user object used in a feature flag evaluation. SDKs periodically transmit details for the user object used in a feature flag evaluation as reported by the feature event with a separate index event. Not included if your SDK configuration is set to inline users. Not included if your SDK supports contexts.
  • user: The user object used in a feature flag evaluation. Only included if your SDK configuration is set to inline users. Not included if your SDK supports contexts.

​
Index events

By default, LaunchDarkly does not export index events. To export index events, start a Support ticket. To learn more, read How to enable index events for Data Export.
Server-side SDKs send index events periodically to describe the attributes of contexts referenced by the contextKey in feature events. An example index event is shown below: 
    // this example is from Data Export event schema version 2
    {
      "kind": "index",
      "id": "abc123xyz",
      "creationDate": 1462220944000,
      "context": {
        "key": "example-context-key",
        "kind": "user",
        "name": "Sandy Smith",
        "jobFunction": "doctor",
        "moreComplex": {
          "city": "Springfield",
          "moreThanOne": [1, 2, 3]
        }
      }
    }
Here is a list of index event properties:
  • kind: The kind of an index event is index.
  • creationDate: The time this context was recorded at UNIX epoch time in milliseconds.
  • context: The same schema as context objects for feature flag evaluation.
  • userKey: The same schema as userKey for feature flag evaluation. Not included if your SDK configuration is set to inline users. Not included if your SDK supports contexts.
  • user: The same schema as user objects for feature flag evaluation. Only included if your SDK configuration is set to inline users. Not included if your SDK supports contexts.
Server-side SDKs have internal logic that determines whether it is necessary to send an index event. SDKs do not create index events for every flag evaluation. If the SDKs identify the same context multiple times in succession, the SDK does not send multiple index events. The SDK identifies contexts based on the contexts’ keys.
Client-side SDKs do not send index events. Instead, client-side SDKs send identify events when the SDK initializes, which include all of the context properties.

​
Identify events

identify events are produced when the client application calls the identify SDK method. identify events have a similar structure to index events. An example identify event is shown below: 
    // this example is from Data Export event schema version 2

    {
      "kind": "identify",
      "id": "abc123xyz",
      "creationDate": 1462220944000,
      "context": {
        "key": "example-context-key",
        "kind": "user",
        "name": "Sandy Smith",
        "jobFunction": "doctor",
        "moreComplex": {
          "city": "Springfield",
          "moreThanOne": [1, 2, 3]
        }
      }
    }
Here is a list of identify event properties:
  • kind: The kind of an identify event is identify.
  • creationDate: The time this context was recorded at UNIX epoch time in milliseconds.
  • context: The same schema as context objects for feature flag evaluation.
  • userKey: The same schema as userKey for feature flag evaluation. Not included if your SDK configuration is set to inline users. Not included if your SDK supports contexts.
  • user: The same schema as user objects for feature flag evaluation. Only included if your SDK configuration is set to inline users. Not included if your SDK supports contexts.

​
Click events

JavaScript-based SDKs produce click events when an end user clicks on an HTML element matching a CSS selector configured on an experiment metric. To learn more, read Clicked or tapped conversion metrics. An example click event is shown below: 
    // this example is from Data Export event schema version 2

    {
      "kind": "click",
      "id": "abc123xyz",
      "key": "<internal id, not used>",
      "url": "https://example.com/",
      "creationDate": 16420388151234,
      "selector": "button.click-track",
      "contextKeys": {
        "user": "Sandy",
        "anonymousUser": "123213421231"
      }
    }

​
Page view events

JavaScript-based SDKs produce pageview events when an end user loads a page with URL matching a regular expression configured on an experiment metric. To learn more, read Page viewed conversion metrics. An example pageview event is shown below: 
    // this example is from Data Export event schema version 2

    {
      "kind": "pageview",
      "id": "abc123xyz",
      "key": "<internal id, not used>",
      "url": "https://example.com/",
      "creationDate": 16420388151234,
      "contextKeys": {
        "user": "Sandy",
        "anonymousUser": "123213421231"
      }
    }

​
Custom events

SDKs produce custom events:
  • when your application calls any of the SDK’s track* methods
  • automatically when the SDK is initialized, when an error occurs, and when other web vitals occur, if you are using an observability SDK

Try it in your SDK: Sending custom events
The data event kind is not available for mParticle or Twilio Segment events.
An example custom event is shown below. The metricValue field will not appear if the event did not provide a metric value. 
    // this example is from Data Export event schema version 2

    {
      "kind": "custom",
      "id": "abc123xyz",
      "key": "example-event-key",
      "creationDate": 16420388151234,
      "data": { "arbitrary": "customer-provided-data" },
      "metricValue": 5.3,
      "samplingRatio": 10,
      "contextKeys": {
        "user": "example-context-key"
      },
      "context": {
        "key": "example-context-key",
        "kind": "user",
        "name": "Sandy"
      }
    }
If the custom events are generated by your application when it calls an SDK’s track method, then the data field will include the information that you pass to the track call. If the custom events are generated by LaunchDarkly, for example if you are using a LaunchDarkly observability SDK, then the data field will have a specific structure. For instance, in custom events that are automatically created by LaunchDarkly because of an error, the data field is a JSON object that always includes a sessionId.

​
Summary events

By default, LaunchDarkly does not export summary events. To export summary events, start a Support ticket.
SDKs send summary events periodically to describe a set of feature evaluations. Summary events include all feature evaluations, regardless of whether the trackEvents field was set for individual flags. They are sent when events are flushed, or during the configured flush interval. To learn more, read Event buffering and sending. An example summary event is shown below: 
    // this example is from Data Export event schema version 2

    {
      "kind": "summary",
      "id": "abc123xyz",
      "startDate": 1517350765387,
      "endDate": 1517350825243,
      "features": {
        "example-flag-key": {
          "default": true,
          "counters": [
            {
              "value": true,
              "count": 10,
              "version": 3
            }
          ],
          "contextKinds": ["user", "device"]
        }
      }
    }
The summary event represents a set of feature flag evaluations occurring during an interval defined by startDate and endDate, sorted by feature flag. Each feature flag includes the following details: | Field
Meaning
| --- | | startDate | The timestamp of the first feature flag evaluation included in this packet. This value is a UNIX epoch time in milliseconds. | | endDate | The timestamp of the last feature flag evaluation included in this packet. This value is a UNIX epoch time in milliseconds. | | default | The default value the SDK received for the feature, sampled at some point during the interval. | | counters | A set of counters as described below. | | contextKind (version 4 only) | The context kinds used to evaluate the flag. | The counters field is an array of objects with the following contents: | Field
Meaning
| --- | | version | The version of the feature flag evaluated. | | value | The value the SDK returned for the flag evaluation. | | variation | A zero-based index into the list of variations. If LaunchDarkly does not provide this field, it means the SDK returned a fallback value. | | count | The number of times this value/version/variation combination was an evaluation result during the interval. | | unknown (optional) | If this is present and true, it indicates that no flag by this name was known to LaunchDarkly, and therefore the SDK returned the fallback value. |

​
Debug events

The debug event is a variant of the feature event, with two differences. It has kind set to debug and it inlines the context value. The information can help you to troubleshoot feature flag evaluations more quickly. SDKs send debug events only if the debugEventsUntilDate attribute is set for a feature flag and the attribute indicates a UNIX epoch timestamp in milliseconds that has not yet elapsed. To set the debugEventsUntilDate attribute for a feature flag, navigate to the Live events page. Find a summary event for the flag you are interested in and click Full fidelity details. debug events are not controlled by the trackEvents field. Here is an example debug event: 
    // this example is from Data Export event schema version 2

     {
        "kind": "debug",
        "id": "abc123xyz",
        "context": {
          "key": "example-context-key",
          "kind": "user",
          "name": "Sandy"
        },
        "creationDate": 1462220944000,
        "key": "example-flag-key",
        "value": false,
        "default": false,
        "version": 42,
        "prereqOf": "parent-flag-key-456def"
      }
Here is a list of the debug event properties:
  • kind: The kind of a debug event is debug.
  • context: The same schema as context objects for feature flag evaluation.
  • creationDate: When the SDK requested the feature flag, as UNIX epoch time in milliseconds.
  • key: The key of the feature flag requested.
  • value: The value of the feature flag returned by feature flag evaluation.
  • default: Optional. This will be true if the feature flag evaluation failed and the SDK served the fallback value instead. This field will be false or omitted if the SDK did not serve the fallback value.

Try it in your SDK: Evaluating flags