Skip to content

Commit cd99c35

Browse files
toddbaertjustinabrahmsbeeme1mrroncohenkozikow
authored
feat: tracking (#268)
Adds tracking --------- Signed-off-by: Todd Baert <[email protected]> Co-authored-by: Justin Abrahms <[email protected]> Co-authored-by: Michael Beemer <[email protected]> Co-authored-by: Ron Cohen <[email protected]> Co-authored-by: Robert Kozikowski <[email protected]> Co-authored-by: Ryan Lamb <[email protected]> Co-authored-by: Nicklas Lundin <[email protected]>
1 parent df1f62e commit cd99c35

File tree

5 files changed

+206
-32
lines changed

5 files changed

+206
-32
lines changed

‎specification.json

+65
Original file line numberDiff line numberDiff line change
@@ -508,6 +508,13 @@
508508
"RFC 2119 keyword": "MAY",
509509
"children": []
510510
},
511+
{
512+
"id": "Condition 2.7.1",
513+
"machine_id": "condition_2_7_1",
514+
"content": "The `provider` MAY define a function for tracking the occurrence of a particular user action or application state, with parameters `tracking event name` (string, required), `evaluation context` (optional) and `tracking event details` (optional) which returns nothing.",
515+
"RFC 2119 keyword": "MAY",
516+
"children": []
517+
},
511518
{
512519
"id": "Requirement 3.1.1",
513520
"machine_id": "requirement_3_1_1",
@@ -1044,6 +1051,64 @@
10441051
"content": "If the provider emits an event, the value of the client's `provider status` MUST be updated accordingly.",
10451052
"RFC 2119 keyword": "MUST",
10461053
"children": []
1054+
},
1055+
{
1056+
"id": "Condition 6.1.1",
1057+
"machine_id": "condition_6_1_1",
1058+
"content": "The implementation uses the dynamic-context paradigm.",
1059+
"RFC 2119 keyword": null,
1060+
"children": [
1061+
{
1062+
"id": "Conditional Requirement 6.1.1.1",
1063+
"machine_id": "conditional_requirement_6_1_1_1",
1064+
"content": "The `client` MUST define a function for tracking the occurrence of a particular action or application state, with parameters `tracking event name` (string, required), `evaluation context` (optional) and `tracking event details` (optional), which returns nothing.",
1065+
"RFC 2119 keyword": "MUST",
1066+
"children": []
1067+
}
1068+
]
1069+
},
1070+
{
1071+
"id": "Condition 6.1.2",
1072+
"machine_id": "condition_6_1_2",
1073+
"content": "The implementation uses the static-context paradigm.",
1074+
"RFC 2119 keyword": null,
1075+
"children": [
1076+
{
1077+
"id": "Conditional Requirement 6.1.2.1",
1078+
"machine_id": "conditional_requirement_6_1_2_1",
1079+
"content": "The `client` MUST define a function for tracking the occurrence of a particular action or application state, with parameters `tracking event name` (string, required) and `tracking event details` (optional), which returns nothing.",
1080+
"RFC 2119 keyword": "MUST",
1081+
"children": []
1082+
}
1083+
]
1084+
},
1085+
{
1086+
"id": "Requirement 6.1.3",
1087+
"machine_id": "requirement_6_1_3",
1088+
"content": "The evaluation context passed to the provider's track function MUST be merged in the order: API (global; lowest precedence) - transaction - client - invocation (highest precedence), with duplicate values being overwritten.",
1089+
"RFC 2119 keyword": "MUST",
1090+
"children": []
1091+
},
1092+
{
1093+
"id": "Requirement 6.1.4",
1094+
"machine_id": "requirement_6_1_4",
1095+
"content": "If the client's `track` function is called and the associated provider does not implement tracking, the client's `track` function MUST no-op.",
1096+
"RFC 2119 keyword": "MUST",
1097+
"children": []
1098+
},
1099+
{
1100+
"id": "Requirement 6.2.1",
1101+
"machine_id": "requirement_6_2_1",
1102+
"content": "The `tracking event details` structure MUST define an optional numeric `value`, associating a scalar quality with an `tracking event`.",
1103+
"RFC 2119 keyword": "MUST",
1104+
"children": []
1105+
},
1106+
{
1107+
"id": "Requirement 6.2.2",
1108+
"machine_id": "requirement_6_2_2",
1109+
"content": "The `tracking event details` MUST support the inclusion of custom fields, having keys of type `string`, and values of type `boolean | string | number | structure`.",
1110+
"RFC 2119 keyword": "MUST",
1111+
"children": []
10471112
}
10481113
]
10491114
}

‎specification/glossary.md

+5
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ This document defines some terms that are used across this specification.
3636
- [Transaction Context Propagator](#transaction-context-propagator)
3737
- [Evaluating Flag Values](#evaluating-flag-values)
3838
- [Resolving Flag Values](#resolving-flag-values)
39+
- [Tracking Event](#tracking-event)
3940
- [Flagging specifics](#flagging-specifics)
4041
- [Flag](#flag)
4142
- [Flag Set](#flag-set)
@@ -148,6 +149,10 @@ The process of retrieving a feature flag value in it's entirety, including:
148149

149150
The process of a provider retrieving a feature flag value from it's particular source-of-truth.
150151

152+
### Tracking Event
153+
154+
A particular user action or application state representing a business objective or outcome, identified by a unique string, and recorded using the [tracking API](./sections/06-tracking.md).
155+
151156
## Flagging specifics
152157

153158
```mermaid

‎specification/sections/02-providers.md

+31
Original file line numberDiff line numberDiff line change
@@ -261,3 +261,34 @@ class MyProvider implements Provider {
261261
Providers may maintain remote connections, timers, threads or other constructs that need to be appropriately disposed of.
262262
Provider authors may implement a `shutdown` function to perform relevant clean-up actions.
263263
Alternatively, implementations might leverage language idioms such as auto-disposable interfaces or some means of cancellation signal propagation to allow for graceful shutdown.
264+
265+
### 2.7. Tracking Support
266+
267+
[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
268+
269+
Some flag management systems support tracking functionality, which can be used to associate feature flag evaluations with subsequent user actions or application state.
270+
271+
See [tracking](./06-tracking.md).
272+
273+
#### Condition 2.7.1
274+
275+
> The `provider` **MAY** define a function for tracking the occurrence of a particular user action or application state, with parameters `tracking event name` (string, required), `evaluation context` (optional) and `tracking event details` (optional) which returns nothing.
276+
277+
```java
278+
class MyProvider implements Tracking {
279+
//...
280+
281+
/**
282+
* Record a tracking event.
283+
*/
284+
void track(String trackingEventName, EvaluationContext context, TrackingEventDetails details): void;
285+
286+
//...
287+
}
288+
```
289+
290+
The track function is a void function (function returning nothing).
291+
The track function performs side effects required to record the `tracking event` in question, which may include network activity or other I/O; this I/O should not block the function call.
292+
Providers should be careful to complete any communication or flush any relevant uncommitted tracking data before they shut down.
293+
294+
See [shutdown](#25-shutdown).

‎specification/sections/06-tracking.md

+95-32
Original file line numberDiff line numberDiff line change
@@ -10,35 +10,98 @@ toc_max_heading_level: 4
1010

1111
## Overview
1212

13-
Experimentation is a primary use case for feature flags.
14-
In practice, this often means flag variants are assigned to users at random or in accordance with a business rule, while the impact of the assigned variant on some business objective is measured.
15-
Vendors and custom solutions often support a _tracking_ or _goal measuring_ API to facilitate the measurement of these business objectives.
16-
17-
### Goals
18-
19-
- Develop official terminology to support consistent implementation
20-
- Specify a flexible API widely compatible with basic vendor functionality
21-
- Define tracking event payload
22-
- Define tracking event identifier
23-
- Support A/B testing and experimentation use-cases
24-
- Support client and server paradigms
25-
- Provide recommendations around:
26-
- Async vs sync
27-
- Flushing mechanisms
28-
- Event batching
29-
30-
### Non-goals
31-
32-
- Creating an experimentation platform
33-
- Covering every user-tracking use case
34-
- We will not define any data aggregation mechanisms
35-
- We will not focus on "metrics", but instead, "facts"
36-
37-
### Design Principles
38-
39-
We value the following:
40-
41-
- Adherence to, and compatibility with OpenFeature semantics
42-
- Maximum compatibility and ease-of-adoption for existing solutions
43-
- Minimum traffic and payload size
44-
- Ease-of-use for application authors, integrators, and provider authors (in that order)
13+
The `tracking API` enables the association of feature flag evaluations with subsequent actions or application states, in order to facilitate experimentation and analysis of the impact of feature flags on business objectives.
14+
15+
Combined with hooks which report feature flag evaluations to the analytics platform in question, tracking can allow for robust experimentation even for flag management systems that don't support tracking directly.
16+
17+
```mermaid
18+
sequenceDiagram
19+
Evaluation API->>+Tracking Hook: evaluate
20+
Tracking Hook->>Analytics Platform: before
21+
Tracking Hook->>Analytics Platform: after
22+
Tracking Hook->>-Evaluation API: evaluate
23+
Evaluation API->>Analytics Platform: track
24+
```
25+
26+
### 6.1. Tracking API
27+
28+
#### Condition 6.1.1
29+
30+
> The implementation uses the dynamic-context paradigm.
31+
32+
see: [dynamic-context paradigm](../glossary.md#dynamic-context-paradigm)
33+
34+
##### Conditional Requirement 6.1.1.1
35+
36+
> The `client` **MUST** define a function for tracking the occurrence of a particular action or application state, with parameters `tracking event name` (string, required), `evaluation context` (optional) and `tracking event details` (optional), which returns nothing.
37+
38+
```java
39+
// example tracking event recording that a subject reached a page associated with a business goal
40+
client.track("visited-promo-page", evaluationContext);
41+
42+
// example tracking event recording that a subject performed an action associated with a business goal, with the tracking event details having a particular numeric value
43+
client.track("clicked-checkout", evaluationContext, new TrackingEventDetails(99.77));
44+
45+
// example tracking event recording that a subject performed an action associated with a business goal, with the tracking event details having a particular numeric value
46+
client.track("clicked-checkout", evaluationContext, new TrackingEventDetails(99.77).add("currencyCode", "USD"));
47+
```
48+
49+
See [evaluation context](../types.md#evaluation-context), [tracking event details](#62-tracking-event-details).
50+
51+
#### Condition 6.1.2
52+
53+
[![experimental](https://img.shields.io/static/v1?label=Status&message=experimental&color=orange)](https://github.com/open-feature/spec/tree/main/specification#experimental)
54+
55+
> The implementation uses the static-context paradigm.
56+
57+
see: [static-context paradigm](../glossary.md#static-context-paradigm)
58+
59+
##### Conditional Requirement 6.1.2.1
60+
61+
> The `client` **MUST** define a function for tracking the occurrence of a particular action or application state, with parameters `tracking event name` (string, required) and `tracking event details` (optional), which returns nothing.
62+
63+
The track function is a void function (function returning nothing).
64+
Though it may be associated with network activity or other I/O, it need not be awaited by application authors.
65+
66+
```java
67+
// example tracking event recording that a subject reached a page associated with a business goal
68+
client.track("visited-promo-page");
69+
70+
// example tracking event recording that a subject performed an action associated with a business goal, with the tracking event details having a particular numeric value
71+
client.track("clicked-checkout", new TrackingEventDetails(99.77));
72+
73+
// example tracking event recording that a subject performed an action associated with a business goal, with the tracking event details having a particular numeric and some additional details
74+
client.track("clicked-checkout", new TrackingEventDetails(99.77).add("currencyCode", "USD"));
75+
```
76+
77+
#### Requirement 6.1.3
78+
79+
> The evaluation context passed to the provider's track function **MUST** be merged in the order: API (global; lowest precedence) -> transaction -> client -> invocation (highest precedence), with duplicate values being overwritten.
80+
81+
The SDK passes a merged evaluation context to the provider's track function similarly to the manner it does in resolvers.
82+
83+
See: [context levels and merging](./03-evaluation-context.md#32-context-levels-and-merging).
84+
85+
#### Requirement 6.1.4
86+
87+
> If the client's `track` function is called and the associated provider does not implement tracking, the client's `track` function **MUST** no-op.
88+
89+
### 6.2. Tracking Event Details
90+
91+
The `tracking event details` structure defines optional data pertinent to a particular `tracking event`.
92+
93+
#### Requirement 6.2.1
94+
95+
> The `tracking event details` structure **MUST** define an optional numeric `value`, associating a scalar quality with an `tracking event`.
96+
97+
`Value` is a well-defined field which some providers may map to equivalent numeric values in their API.
98+
99+
See [provider tracking support](./02-providers.md#27-tracking-support).
100+
101+
#### Requirement 6.2.2
102+
103+
> The `tracking event details` **MUST** support the inclusion of custom fields, having keys of type `string`, and values of type `boolean | string | number | structure`.
104+
105+
The `tracking event details` supports the addition of arbitrary fields, including nested objects, similar to the `evaluation context` and object-typed flag values.
106+
107+
See [structure](../types.md#structure), [evaluation context](.//03-evaluation-context.md).

‎specification/types.md

+10
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,10 @@ An enumerated error code represented idiomatically in the implementation languag
113113
| PROVIDER_FATAL | The provider has entered an irrecoverable error state. |
114114
| GENERAL | The error was for a reason not enumerated above. |
115115

116+
### Evaluation Context
117+
118+
See [evaluation context](./sections/03-evaluation-context.md).
119+
116120
### Evaluation Options
117121

118122
A structure containing the following fields:
@@ -184,3 +188,9 @@ An enumeration of provider events.
184188

185189
A function or method which can be associated with a `provider event`, and runs when that event occurs.
186190
It declares an `event details` parameter.
191+
192+
### Tracking Event Details
193+
194+
A structure which supports definition of arbitrary properties, including nested objects, similar to the `evaluation context` and object-typed flag values.
195+
196+
See [tracking event details](./sections/06-tracking.md#62-tracking-event-details), [evaluation context](#evaluation-context).

0 commit comments

Comments
 (0)