Data export schema reference

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.

• mParticle schema reference
• Segment schema reference

These events are described in more detail below.

Event Kinds

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

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}
COPY

• 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    "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 }
COPY

• 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 or the reserved word "user" 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.

• 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

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  }
COPY

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

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

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}
COPY

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.

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}
COPY

Summary events

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}
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: