Data Export schema reference

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, contact Support.
• 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:

• mParticle schema reference
• Segment schema reference

These events are described in more detail below.

Event kinds

This table lists event kinds:

SDK versioning for events

Older SDKs always send feature events regardless of whether detailed tracking is enabled for that flag. Only newer SDKs generate the summary and index events described below.

Older SDKs will also send user attributes as an object inside feature events instead of just providing a "contextKey" that can reference context data sent in a prior index event.

Understanding 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": {...},
  "version": 2,
}
COPY

• project: The ID of the LaunchDarkly project associated with the event.
• environment: The ID of the LaunchDarkly environment associated with the event.
• version: The event version. Events sent from SDKs upgraded for contexts are version 2. Older events are version 1 and have different schemas.
• event: The event itself. It is an object with a structure described below, depending on the kind of event.

Feature events

Feature events represent individual flag evaluations and are considered "full fidelity" events.

Here is an example feature event:

{
  "kind": "feature",
  "creationDate": 1462220944000,
  "key": "flag-key-123abc",
  "variation": 0,
  "variationName": "my variation",
  "value": false,
  "default": false,
  "version": 42,
  "reason": {
    "kind": "FALLTHROUGH"
  },
  "prereqOf": "prereq-flag-key-123abc",
  "contextKeys": {
    "user": "sandy",
    "anonymousUser": "123213421231"
  }
}
COPY

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, and other flag types are numbered starting with 0 for their 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: (Optional) This value is set to true if feature flag evaluation failed, in which case the value returned was the default value passed to variation. If the default field is omitted, it is assumed to be false.
• 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: attribute should be set to a flag key if this flag evaluation was only performed in order to determine whether the prerequisite values were met for the indicated flag.
• contextKeys (version 2 only): 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.
• contextKind (version 1 only): The kind of context which generated an event. This will only be "anonymousUser" for events generated on behalf of an anonymous user. It is omitted for events generated on behalf of a non-anonymous user.
• userKey (version 1 only): 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.

Index events

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:

{
  "kind": "index",
  "context": {
    "key": "context-key-123abc",
    "kind": "user",
    "name": "Sandy Smith",
    "jobFunction": "doctor",
    "moreComplex": {
      "city": "Springfield",
      "moreThanOne": [1, 2, 3]
    }
  },
  "creationDate": 1462220944000
}
COPY

Here is a list of index event properties:

• kind: The kind of an index event is index.
• context (version 2 only): The same schema as context objects for feature flag evaluation.
• creationDate: The time this context was recorded at UNIX epoch time in milliseconds.
• user (version 1 only): The same schema as user objects for feature flag evaluation.

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:

{
  "kind": "identify",
  "context": {
    "key": "context-key-123abc",
    "kind": "user",
    "name": "Sandy Smith",
    "jobFunction": "doctor",
    "moreComplex": {
      "city": "Springfield",
      "moreThanOne": [1, 2, 3]
    }
  },
  "creationDate": 1462220944000
}
COPY

Here is a list of identify event properties:

• kind: The kind of an identify event is identify.
• context (version 2 only): The same schema as context objects for feature flag evaluation.
• creationDate: The time this context was recorded at UNIX epoch time in milliseconds.
• user (version 1 only): The same schema as user objects for feature flag evaluation.

Click events

The JavaScript and React 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 Click conversion metrics.

An example click event is shown below:

{
  "kind": "click",
  "key": "click-metric-key-123abc",
  "url": "https://example.com/",
  "creationDate": 16420388151234,
  "selector": "button.click-track"
  "contextKeys": {
    "user": "Sandy",
    "anonymousUser": "123213421231"
  }
}
COPY

Page view events

The JavaScript and React 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 view conversion metrics.

An example pageview event is shown below:

{
  "kind": "pageview",
  "key": "page-view-metric-key-123abc",
  "url": "https://example.com/",
  "creationDate": 16420388151234,
  "contextKeys": {
    "user": "Sandy",
    "anonymousUser": "123213421231"
  }
}
COPY

Custom events

SDKs produce custom events when the client application calls the SDK's track method. To learn more, read Sending custom events.

An example custom event is shown below. Note that the metricValue field will not appear if a metric value was not provided by the event.

{
  "kind": "custom",
  "key": "custom-metric-key-123abc",
  "creationDate": 16420388151234,
  "data": { "arbitrary": "customer-provided-data" },
  "metricValue": 5,
  "contextKeys": {
    "user": "Sandy",
    "anonymousUser": "123213421231"
  }
}
COPY

Summary events

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.

An example summary event is shown below:

{
  "startDate": 1517350765387,
  "endDate": 1517350825243,
  "features": {
    "flag-key-123abc": {
      "default": "default-value",
      "counters": [
        {
          "value": "result-value",
          "version": 17,
          "count": 23,
          "variation": 1
        },
        {
          "value": "another-value",
          "version": 17,
          "count": 2,
          "variation": 0
        }
      ],
      "contextKinds": ["user", "device"]
    }
  }
}
COPY

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:

The counters field is an array of objects with the following contents:

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. 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. debug events are not controlled by the trackEvents field.

Here is an example debug event:

{
    "kind": "debug",
    "context": {
      "key": "context-key-123abc",
      "kind": "user",
      "name": "Sandy"
    },
    "creationDate": 1462220944000,
    "key": "flag-key-123abc",
    "value": false,
    "default": false,
    "version": 42,
    "prereqOf": "parent-flag-key-456def"
  }
COPY

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 default flag value that your app passed into the SDK evaluation was used instead. This field will be false or omitted if the default flag value was not used.