Data export schema reference
Read time: 4 minutes
Last edited: Apr 02, 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
Description | Event kind |
---|---|
feature | This 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. |
index | This 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. |
identify | This 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. |
custom | This event type passes data provided in an explicit custom call to the SDK. |
alias | This 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 |
summary | This event describes a roll-up of individual feature evaluations over an interval. To export summary events, contact LaunchDarkly Support. |
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.
The minimum SDK version numbers for SDKs support the new summary
and index
events and limit the sending of "feature" events are listed below:
.NET: 4.0.0
Go: 4.0.0 (aka v4)
Java: 4.0.0
Node: 5.0.0
PHP: 4.0.0
Python: 6.0.0
Ruby: 4.0.0
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 currently in use (it is always1
), but may be used in the future if event schemas change.event
: The event itself. It is an object with a structure described below, depending on thekind
of event.
Feature events
Feature
events represent individual flag evaluations and are considered "full fidelity" events.
An example feature event is pictured below:
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 }
kind
: The kind for a feature event isfeature
. A feature event will only be generated if thetrackEvents
attribute of the flag is set totrue
. 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 or the reserved word "user" for events generated on behalf of a non-anonymous useruserKey
: The key of the user object used in a feature flag evaluation. Details for theuser
object used in a feature flag evaluation as reported by the "feature" event are transmitted periodically with a separateindex
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 as0
or1
fortrue
andfalse
, and other flag types are numbered starting with0
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 totrue
if feature flag evaluation failed, in which case the value returned was the default value passed tovariation
. If the default field is omitted, it is assumed to befalse
.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.
If a feature event was generated through a "variation detail" method, the event will have a reason
property with the JSON representation of the evaluation reason.
Index events
By default, we do not export index events. To export index events, contact LaunchDarkly Support.
Index events are sent periodically to describe the attributes of users referenced by the "userKey" in feature
events.
An example index
event is pictured 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 }
kind
: The kind of an index event isindex
.user
: The same schema asuser
objects for feature flag evaluation.creationDate
: The time this user was recorded at Unix epoch time in milliseconds.SDKs determine when index events are sentThe SDKs have internal logic that determines whether it is necessary to send an "index" event. Index events are not created for every flag evaluation. If the same user (as defined by their key) is seen multiple times in succession, multiple index events will not be sent.
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 pictured 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": 146222094400013}
kind
: The kind of an identify event isidentify
.user
: The same schema asuser
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
.
The data
event kind is not available for mParticle or Segment events.
An example custom event is pictured 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.
To read about how alias events function in mParticle and Segment destinations, see their respective schema references.
An example alias event is pictured 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
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 pictured 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)2930 }],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:
Field | Meaning |
---|---|
default | The default value the SDK received for the feature (sampled at some point during the interval). |
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. |
counters | A set of counters as described below. |
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 returned by the SDK for the flag evaluation. |
variation | A zero-based index into the list of variations. If this field not provided, a default value was used. |
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 default value was returned). |