feat: tracking

[toddbaert]

Adds tracking

---

This PR is a first pass at a relatively simple tracking API. The main purpose is to close what is more or less the last gap between the OpenFeature API and that of most SDKs (many SDKs which we currently support have some kind of simple "track" method analogous to what's proposed here). Preceding discussion can be found here.

Some notable choices:

• I've used the term "occurrence" instead of "event" to minimize terminology overloading
• I've ordered the parameters for the tracking method occurrenceKey/context/occurrenceDetails.
• I've specified the track method should never block but instead queue any async work; we agreed there's no reason an application author would ever want to await a I/O associated with a single track call; most providers will batch these, I assume
• I've made value a "first class" property of the otherwise free-form OccurrenceDetails type, so it can be easily mapped into the equivalent field of various providers (something like targetingKey)

[toddbaert]

Draft JS implementation available here: open-feature/js-sdk#1020

[toddbaert]

@moredip suggests we perhaps use something other than "occurrence" (see comment here in draft JS implementation).

I went with "occurrence" to reduce collision with our existing event concepts (for example, we already have event and eventDetails objects), but we can disambiguate these other ways:

Currently I've proposed:

void track(String occurrenceKey, EvaluationContext context, OccurrenceDetails details): void;

but an obvious alternative would be:

void track(String trackingEventKey, EvaluationContext context, TrackingEventDetails details): void;

I'm also not sure if trackingEventId or trackingEventKey is better; we use key for flags themselves, but a key to me suggests a string index a specific set (perfect for flags in flag-sets) whereas an id might be a "softer" reference, such as a UUID.

Does anyone have points in favor of one or the other?

[toddbaert]

Demo of some of these features: https://www.youtube.com/watch?v=Od-7Pjs2dKQ&t=436s

[roncohen]

Does anyone have points in favor of one or the other?

The occurrence terminology threw me off initially. I understand the background for picking occurrence over event/trackingEvent, but I feel that in the context of the track call, the confusion should be manageable and the advantage of aligning on known terminology is substantial.

So I’m in favor of going with trackingEvent, trackEvent or simply event (and trackingEventKey, trackEventKey or eventKey respectively)

I'm also not sure if trackingEventId or trackingEventKey is better

Agreed that “key” is better here. Some platforms give specific events UUIDs for deduplication purposes etc which is not what we’re talking about here. I think “name” could also be a contender. Segment refers to this as the name (e.g. “event name”): https://segment.com/docs/connections/spec/track/

[roncohen]

In the interest of moving this forward, I'd go for:

void track(String trackingEventName, EvaluationContext context, TrackingEventDetails details): void;

[toddbaert]

In the interest of moving this forward, I'd go for:

void track(String trackingEventName, EvaluationContext context, TrackingEventDetails details): void;

I like this and based on slack we have a consensus. Will update.

[toddbaert]

I've made updates based on the most recent feedback, and rebased on main. As usual with spec PRs, we want a wide consensus; so far I think I've seen that represented in this PR and in various meetings and communications in Slack.

I will leave this PR open for additional comments, but I plan to merge it early next week. If you have comments or concerns, please voice them here before then! 🙏

[roncohen]

Nice @toddbaert. Looks like there's still some "occurrence" terminology left in this PR.

[toddbaert]

Nice @toddbaert. Looks like there's still some "occurrence" terminology left in this PR.

Nice catch, @roncohen . I think I got them all this time 😅 . There's still a few cases of the word "occurrence" but I think they are simply descriptive, not params/types.