Data Export schema reference
Read time: 5 minutes
Last edited: May 31, 2023
Overview
This topic explains the schema of Data Export events.
Data Export exposes the following kinds of events:
feature
eventsindex
eventsidentify
eventsclick
eventspage view
eventscustom
eventssummary
events. To exportsummary
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:
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 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 Segment or mParticle destinations. To export index events, contact Support. |
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 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 passes data provided in an explicit track call to the SDK. |
summary | This event kind describes a roll-up of individual feature evaluations over an interval. To export summary events, contact Support. |
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 Segment and mParticle destinations.
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.
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 Settings tab or an environment's Edit panel. By default, LaunchDarkly does not export summary
events. To export summary
events, contact Support.
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,}
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 version2
. Older events are version1
and have different schemas.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.
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"}}
Here is a list of feature
event properties:
kind
: The kind for afeature
event isfeature
. An SDK only generates afeature
event if the you set thetrackEvents
attribute of the flag totrue
. 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 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 thedefault
field is omitted, it is assumed to befalse
.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 totrue
. 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.
- Evaluations that were part of an experiment have the optional
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 thecontext
object used in a feature flag evaluation. SDKs periodically transmit details for thecontext
object used in a feature flag evaluation as reported by the "feature" event with a separateindex
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 separateindex
event.
Index events
index
event exportsBy default, LaunchDarkly does not export index
events. To export index
events, contact Support.
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}
Here is a list of index
event properties:
kind
: The kind of anindex
event isindex
.context
(version 2 only): The same schema ascontext
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.
index
eventsServer-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:
{"kind": "identify","context": {"key": "context-key-123abc","kind": "user","name": "Sandy Smith","jobFunction": "doctor","moreComplex": {"city": "Springfield","moreThanOne": [1, 2, 3]}},"creationDate": 1462220944000}
Here is a list of identify
event properties:
kind
: The kind of anidentify
event isidentify
.context
(version 2 only): The same schema ascontext
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 asuser
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"}}
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"}}
Custom events
SDKs produce custom
events when the client application calls the SDK's track method. To learn more, read Sending custom events.
The data
event kind is not available for mParticle or Segment 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"}}
Summary events
summary
event exportsBy default, we do not export summary
events. To export summary
events, contact Support.
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"]}}}
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 2 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. 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"}
Here is a list of the debug
event properties:
kind
: The kind of adebug
event is"debug"
.context
: The same schema ascontext
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 betrue
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 befalse
or omitted if the default flag value was not used.