• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Data export schema reference

Read time: 4 minutes
Last edited: Nov 17, 2021

Overview

This topic explains the schema of Data Export events.

Data Export exposes five different kinds of events:

  • Feature events
  • Index events
  • Identify events
  • Custom events
  • Alias events
  • Summary events. To export summary events, contact LaunchDarkly Support.

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 events kinds:

DescriptionEvent kind
featureThis event includes full-fidelity details of each individual feature flag evaluation. These are only present if detailed tracking is explicitly enabled for a feature flag, or if an older SDK is in use.
indexThis event type contains details about a user used in feature evaluation for a particular user key. This event kind is not available for Segment or mParticle destinations. To export index events, contact LaunchDarkly Support.
identifyThis event type passes details about a user provided in an explicit identify call to the SDK. This event kind is not available for Segment or mParticle destinations.
customThis event type passes data provided in an explicit custom call to the SDK.
aliasThis event includes information necessary to correlate a user known by two different user keys, for example an anonymous user key and a logged-in key
summaryThis event describes a roll-up of individual feature evaluations over an interval. To export summary events, contact LaunchDarkly Support.
mParticle and Segment schema differences

The index and identify event kinds are not available for Segment and mParticle destinations.

SDK versioning for events

Older SDKs always send feature events regardless of whether detailed tracking is enabled for that flag. The summary and index events described below are also only generated only by newer SDKs.

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

Enabling detailed analytics events

To see "feature" events, in addition to index, identify, and custom events, for a feature flag using recent SDKs, select “Send detailed event information for this flag” in the Settings menu for a feature flag or environment. By default, LaunchDarkly does not export summary events. To export summary events, contact LaunchDarkly Support.

Understanding event type structures

Each of these events are sent as JSON files to your destinations.

All events have the following top level structure:

1{
2 "project": "5744c96707c9900708000004",
3 "environment": "578d1e02d2943862c52b9686",
4 "event": {...},
5 "version": 1,
6}
  • project: The ID of the LaunchDarkly project associated with the event.
  • environment: The ID of the LaunchDarkly environment associated with the event.
  • version: Not in use. The version is always 1.
  • 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.

Hereis an example feature event:

1{
2 "kind": "feature",
3 "contextKind": "anonymousUser",
4 "userKey": "feature@test.com",
5 "creationDate": 1462220944000,
6 "key": "my.feature.key",
7 "variation": 0,
8 "variationName": "my variation",
9 "value": false,
10 "default": false,
11 "version": 42,
12 "reason": {
13 "kind": "FALLTHROUGH"
14 },
15 "prereqOf": "parent-flag"
16 }

Here is a list of feature event properties:

  • kind: The kind for a feature event is feature. A feature event will only be generated if the trackEvents attribute of the flag is set to true. This is also controlled by settings in the UI.
  • contextKind: 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: The key of the user object used in a feature flag evaluation. Details for the user object used in a feature flag evaluation as reported by the "feature" event are transmitted periodically with a separate index event.
  • creationDate When the feature flag was requested at UNIX epoch time in milliseconds.
  • key: The key of the feature flag requested.
  • variation: The variation of the flag requested. Flag variation values are stored 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) If a "variation detail" method generates a feature event, the event will have a reason property with the JSON representation of the evaluation reason. Evaluations that were part of an experiment have the inExperiment attribute on the evaluation reason set to true.
  • 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.

Index events

Enabling index event exports

By default, LaunchDarkly does not export index events. To export index events, contact LaunchDarkly Support.

Server-side SDKs send index events periodically to describe the attributes of users referenced by the "userKey" in feature events.

An example index event is shown below:

1{
2 "kind": "index",
3 "user": {
4 "key": "user@test.com",
5 "custom": {
6 "groups": [
7 "microsoft",
8 "google"
9 ]
10 }
11 },
12 "creationDate": 1462220944000,
13 }

Here is a list of index event properties:

  • kind: The kind of an index event is index.
  • user: The same schema as user objects for feature flag evaluation.
  • creationDate: The time this user was recorded at UNIX epoch time in milliseconds.
Server-side SDKs determine when to send index events

Server-side SDKs have internal logic that determine whether it is necessary to send an index event. Index events are not created for every flag evaluation. If the SDKs identify the same user multiple times in succession, the SDK does not send multiple index events. The SDK identifies users based in the users' keys.

Client-side SDKs do not send index events. Instead, Client-side SDKs send identify events when the SDK initalizes, which include all of the user 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:

1{
2 "kind": "identify",
3 "user": {
4 "key": "user@test.com",
5 "custom": {
6 "groups": [
7 "microsoft",
8 "google"
9 ]
10 }
11 },
12 "creationDate": 1462220944000
13}

Here is a list of identify event properties:

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

Custom events

Custom events are produced when the client application calls an SDK method called track.

mParticle and Segment schema differences

The data event kind is not available for mParticle or Segment events.

An example custom event is shown below:

1{
2 "kind": "custom",
3 "user": {
4 "key": "user@test.com"
5 },
6 "creationDate": 1416003645758,
7 "key": "custom.event.key",
8 "data": {
9 "custom": "value"
10 }
11}

Alias events

Alias events are produced when the client application calls the Alias SDK method. They are also emitted automatically by clientside SDKs when an anonymous user identifies as a non-anonymous user.

mParticle and Segment schema differences

To read about how alias events function in mParticle and Segment destinations, see their respective schema references.

An example alias event is shown below:

1{
2 "kind": "alias",
3 "creationDate": 1600376029000,
4 "key": "logged-in-user",
5 "contextKind": "user",
6 "previousKey": "logged-out-user",
7 "previousContextKind": "anonymousUser"
8}

Summary events

Enabling summary event exports

By default, we do not export summary events. To export summary events, contact LaunchDarkly Support.

Summary events are sent periodically by SDKs to describe a set of feature evaluations. Summary events include all feature evaluations, regardless of whether trackEvents field was set for individual flags.

An example summary event is shown below:

1{
2 "startDate": 1517350765387,
3 "endDate": 1517350825243,
4 "features": {
5 "flag-key": {
6 "default": "default-value",
7 "counters": [
8 {
9 "value": "result-value"
10 "version": 17,
11 "count": 23,
12 "variation": 1,
13 },
14 {
15 "value": "another-value"
16 "version": 17,
17 "count": 2,
18 "variation": 0,
19 }
20 ]
21 },
22 "another-flag-key" :{
23 "default": "some-other-result-value",
24 "counters": [{
25 "value": "some-other-result-value",
26 "version": 19,
27 "count": 29,
28 "variation": null (or leave empty)
29
30 }],
31 "nonexistent-flag-key" : {
32 "default": false,
33 "counters": [
34 {
35 "unknown": true,
36 "value": false,
37 "count": 3,
38 }]
39 }
40}

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:

FieldMeaning
defaultThe default value the SDK received for the feature (sampled at some point during the interval).
startDateThe timestamp of the first feature flag evaluation included in this packet. This value is a UNIX epoch time in milliseconds.
endDateThe timestamp of the last feature flag evaluation included in this packet. This value is a UNIX epoch time in milliseconds.
countersA set of counters as described below.

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

FieldMeaning
versionThe version of the feature flag evaluated.
valueThe value returned by the SDK for the flag evaluation.
variationA zero-based index into the list of variations. If this field not provided, a default value was used.
countThe 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 default value was returned).