• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
CLOSE
launchdarkly.com

EDIT ON GITHUB

Data export schema reference

Read time: 3 minutes
Last edited: Jul 12, 2020

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
  • 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

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 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.
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.

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

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 currently in use (it is always 1), 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 the kind 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 "userKey": "feature@test.com",
4 "creationDate": 1462220944000,
5 "key": "my.feature.key",
6 "variation": 0,
7 "variationName": "my variation",
8 "value": false,
9 "default": false,
10 "version": 42,
11 "reason": {
12 "kind": "FALLTHROUGH"
13 },
14 "prereqOf": "parent-flag"
15 }
  • 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.

  • 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.

  • 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

Enabling index event exports

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 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.
    SDKs determine when index events are sent
    The 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": 1462220944000
13}
  • 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 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}

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 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)
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).