feat: Implement tracking

README.md

@@ -107,6 +107,7 @@ print("Value: " + str(flag_value))
 | ✅      | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                              |
 | ✅      | [Domains](#domains)                                                 | Logically bind clients with providers.                                                                                                |
 | ✅      | [Eventing](#eventing)                                               | React to state changes in the provider or flag management system.                                                                     |
+| ✅      | [Tracking](#tracking)                                               | Associate user actions with feature flag evaluations.                                                                                |
 | ✅      | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                           |
 | ✅      | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
 | ✅      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                   |
@@ -185,6 +186,27 @@ client.add_hooks([MyHook()])
 options = FlagEvaluationOptions(hooks=[MyHook()])
 client.get_boolean_flag("my-flag", False, flag_evaluation_options=options)
 ```
+### Tracking
+
+The [tracking API](https://openfeature.dev/specification/sections/tracking/) allows you to use OpenFeature abstractions and objects to associate user actions with feature flag evaluations.
+This is essential for robust experimentation powered by feature flags.
+For example, a flag enhancing the appearance of a UI component might drive user engagement to a new feature; to test this hypothesis, telemetry collected by a [hook](#hooks) or [provider](#providers) can be associated with telemetry reported in the client's `track` function.
+
+```python
+from openfeature.track import TrackingEventDetails
+
+# initialize a client
+client = api.get_client()
+
+# trigger tracking event action
+client.track(
+    'visited-promo-page',
+    evaluation_context=EvaluationContext(),
+    tracking_event_details=TrackingEventDetails(99.77).add("currencyCode", "USD"),
+    )
+```
+
+Note that some providers may not support tracking; check the documentation for your provider for more information.
 
 ### Logging
 

openfeature/client.py

@@ -32,6 +32,7 @@
 )
 from openfeature.provider import FeatureProvider, ProviderStatus
 from openfeature.provider._registry import provider_registry
+from openfeature.track import TrackingEventDetails
 from openfeature.transaction_context import get_transaction_context
 
 __all__ = [
@@ -955,6 +956,33 @@ def add_handler(self, event: ProviderEvent, handler: EventHandler) -> None:
     def remove_handler(self, event: ProviderEvent, handler: EventHandler) -> None:
         _event_support.remove_client_handler(self, event, handler)
 
+    def track(
+        self,
+        tracking_event_name: str,
+        evaluation_context: EvaluationContext | None = None,
+        tracking_event_details: TrackingEventDetails | None = None,
+    ) -> None:
+        """
+        Tracks the occurrence of a particular action or application state.
+
+        :param tracking_event_name: the name of the tracking event
+        :param evaluation_context: the evaluation context
+        :param tracking_event_details: Optional data relevant to the tracking event
+        """
+
+        if evaluation_context is None:
+            evaluation_context = EvaluationContext()
+
+        merged_eval_context = (
+            get_evaluation_context()
+            .merge(get_transaction_context())
+            .merge(self.context)
+            .merge(evaluation_context)
+        )
+        self.provider.track(
+            tracking_event_name, merged_eval_context, tracking_event_details
+        )
+
 
 def _typecheck_flag_value(
     value: typing.Any, flag_type: FlagType

openfeature/provider/__init__.py

@@ -9,6 +9,7 @@
 from openfeature.event import ProviderEvent, ProviderEventDetails
 from openfeature.flag_evaluation import FlagResolutionDetails
 from openfeature.hook import Hook
+from openfeature.track import TrackingEventDetails
 
 from .metadata import Metadata
 
@@ -116,6 +117,13 @@ async def resolve_object_details_async(
         Sequence[FlagValueType] | Mapping[str, FlagValueType]
     ]: ...
 
+    def track(
+        self,
+        tracking_event_name: str,
+        evaluation_context: EvaluationContext | None = None,
+        tracking_event_details: TrackingEventDetails | None = None,
+    ) -> None: ...
+
 
 class AbstractProvider(FeatureProvider):
     def __init__(self, *args: typing.Any, **kwargs: typing.Any) -> None:
@@ -138,6 +146,14 @@ def initialize(self, evaluation_context: EvaluationContext) -> None:
     def shutdown(self) -> None:
         pass
 
+    def track(
+        self,
+        tracking_event_name: str,
+        evaluation_context: EvaluationContext | None = None,
+        tracking_event_details: TrackingEventDetails | None = None,
+    ) -> None:
+        pass
+
     @abstractmethod
     def get_metadata(self) -> Metadata:
         pass

openfeature/provider/in_memory_provider.py

@@ -5,10 +5,11 @@
 from dataclasses import dataclass, field
 
 from openfeature._backports.strenum import StrEnum
-from openfeature.evaluation_context import EvaluationContext
+from openfeature.evaluation_context import EvaluationContext, EvaluationContextAttribute
 from openfeature.exception import ErrorCode
 from openfeature.flag_evaluation import FlagResolutionDetails, Reason
 from openfeature.provider import AbstractProvider, Metadata
+from openfeature.track import TrackingEventDetails
 
 if typing.TYPE_CHECKING:
     from openfeature.flag_evaluation import FlagMetadata, FlagValueType
@@ -22,6 +23,15 @@ class InMemoryMetadata(Metadata):
     name: str = "In-Memory Provider"
 
 
+@dataclass
+class InMemoryTrackingEvent:
+    value: float | None = None
+    details: dict[str, typing.Any] = field(default_factory=dict)
+    eval_context_attributes: Mapping[str, EvaluationContextAttribute] = field(
+        default_factory=dict
+    )
+
+
 T_co = typing.TypeVar("T_co", covariant=True)
 
 
@@ -58,14 +68,24 @@ def resolve(
 
 FlagStorage = dict[str, InMemoryFlag[typing.Any]]
 
+TrackingStorage = dict[str, InMemoryTrackingEvent]
+
 V = typing.TypeVar("V")
 
 
 class InMemoryProvider(AbstractProvider):
     _flags: FlagStorage
+    _tracking_events: TrackingStorage
 
-    def __init__(self, flags: FlagStorage) -> None:
+    # tracking_events defaults to an empty dict
+    def __init__(
+        self, flags: FlagStorage, tracking_events: TrackingStorage | None = None
+    ) -> None:
         self._flags = flags.copy()
+        if tracking_events is not None:
+            self._tracking_events = tracking_events.copy()
+        else:
+            self._tracking_events = {}
 
     def get_metadata(self) -> Metadata:
         return InMemoryMetadata()
@@ -176,3 +196,27 @@ async def _resolve_async(
         evaluation_context: EvaluationContext | None,
     ) -> FlagResolutionDetails[V]:
         return self._resolve(flag_key, default_value, evaluation_context)
+
+    def track(
+        self,
+        tracking_event_name: str,
+        evaluation_context: EvaluationContext | None = None,
+        tracking_event_details: TrackingEventDetails | None = None,
+    ) -> None:
+        value = (
+            tracking_event_details.value if tracking_event_details is not None else None
+        )
+        details = (
+            tracking_event_details.attributes
+            if tracking_event_details is not None
+            else {}
+        )
+        eval_context_attributes = (
+            evaluation_context.attributes if evaluation_context is not None else {}
+        )
+
+        self._tracking_events[tracking_event_name] = InMemoryTrackingEvent(
+            value=value,
+            details=details,
+            eval_context_attributes=eval_context_attributes,
+        )

openfeature/track/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import typing
+from collections.abc import Mapping, Sequence
+
+TrackingValue: typing.TypeAlias = (
+    bool | int | float | str | Sequence["TrackingValue"] | Mapping[str, "TrackingValue"]
+)
+
+
+class TrackingEventDetails:
+    value: float | None
+    attributes: dict[str, TrackingValue]
+
+    def __init__(
+        self,
+        value: float | None = None,
+        attributes: dict[str, TrackingValue] | None = None,
+    ):
+        self.value = value
+        self.attributes = attributes or {}
+
+    def add(self, key: str, value: TrackingValue) -> TrackingEventDetails:
+        self.attributes[key] = value
+        return self

tests/provider/test_in_memory_provider.py

@@ -2,9 +2,15 @@
 
 import pytest
 
+from openfeature.evaluation_context import EvaluationContext
 from openfeature.exception import ErrorCode
 from openfeature.flag_evaluation import FlagResolutionDetails, Reason
-from openfeature.provider.in_memory_provider import InMemoryFlag, InMemoryProvider
+from openfeature.provider.in_memory_provider import (
+    InMemoryFlag,
+    InMemoryProvider,
+    InMemoryTrackingEvent,
+)
+from openfeature.track import TrackingEventDetails
 
 
 def test_should_return_in_memory_provider_metadata():
@@ -194,3 +200,21 @@ async def test_should_resolve_object_flag_from_in_memory():
         assert flag.value == return_value
         assert isinstance(flag.value, dict)
         assert flag.variant == "obj"
+
+
+def test_should_track_event():
+    provider = InMemoryProvider(
+        {"Key": InMemoryFlag("hundred", {"zero": 0, "hundred": 100})}
+    )
+    provider.track(
+        tracking_event_name="test",
+        evaluation_context=EvaluationContext(attributes={"key": "value"}),
+        tracking_event_details=TrackingEventDetails(
+            value=1, attributes={"key": "value"}
+        ),
+    )
+    assert provider._tracking_events == {
+        "test": InMemoryTrackingEvent(
+            value=1, details={"key": "value"}, eval_context_attributes={"key": "value"}
+        )
+    }

tests/test_client.py

@@ -8,7 +8,14 @@
 import pytest
 
 from openfeature import api
-from openfeature.api import add_hooks, clear_hooks, get_client, set_provider
+from openfeature.api import (
+    add_hooks,
+    clear_hooks,
+    get_client,
+    set_evaluation_context,
+    set_provider,
+    set_transaction_context,
+)
 from openfeature.client import OpenFeatureClient, _typecheck_flag_value
 from openfeature.evaluation_context import EvaluationContext
 from openfeature.event import EventDetails, ProviderEvent, ProviderEventDetails
@@ -623,3 +630,39 @@ def test_client_should_merge_contexts():
     assert context.attributes["transaction_attr"] == "transaction_value"
     assert context.attributes["client_attr"] == "client_value"
     assert context.attributes["invocation_attr"] == "invocation_value"
+
+
+def test_client_should_track_event():
+    spy_provider = MagicMock(spec=NoOpProvider)
+    set_provider(spy_provider)
+    client = get_client()
+    client.track(tracking_event_name="test")
+    spy_provider.track.assert_called_once()
+
+
+def test_tracking_merges_evaluation_contexts():
+    spy_provider = MagicMock(spec=NoOpProvider)
+    api.set_provider(spy_provider)
+    client = get_client()
+    set_evaluation_context(EvaluationContext("id", attributes={"key": "eval_value"}))
+    set_transaction_context(
+        EvaluationContext("id", attributes={"transaction_attr": "transaction_value"})
+    )
+    client.track(
+        tracking_event_name="test",
+        evaluation_context=EvaluationContext("id", attributes={"key": "value"}),
+    )
+    spy_provider.track.assert_called_once_with(
+        "test",
+        EvaluationContext(
+            "id", attributes={"transaction_attr": "transaction_value", "key": "value"}
+        ),
+        None,
+    )
+
+
+def test_should_noop_if_provider_does_not_support_tracking(monkeypatch):
+    provider = NoOpProvider()
+    set_provider(provider)
+    client = get_client()
+    client.track(tracking_event_name="test")

tests/track/test_tracking.py

@@ -0,0 +1,39 @@
+from openfeature.track import TrackingEventDetails
+
+
+def test_add_attribute_to_tracking_event_details():
+    tracking_event_details = TrackingEventDetails()
+    tracking_event_details.add("key", "value")
+    assert tracking_event_details.attributes == {"key": "value"}
+
+
+def test_add_attribute_to_tracking_event_details_dict():
+    tracking_event_details = TrackingEventDetails()
+    tracking_event_details.add("key", {"key1": "value1", "key2": "value2"})
+    assert tracking_event_details.attributes == {
+        "key": {"key1": "value1", "key2": "value2"}
+    }
+
+
+def test_get_value_from_tracking_event_details():
+    tracking_event_details = TrackingEventDetails(value=1)
+    assert tracking_event_details.value == 1
+
+
+def test_get_attributes_from_tracking_event_details():
+    tracking_event_details = TrackingEventDetails(
+        value=5.0, attributes={"key": "value"}
+    )
+    assert tracking_event_details.attributes == {"key": "value"}
+
+
+def test_get_attributes_from_tracking_event_details_with_none_value():
+    tracking_event_details = TrackingEventDetails(attributes={"key": "value"})
+    assert tracking_event_details.attributes == {"key": "value"}
+    assert tracking_event_details.value is None
+
+
+def test_get_attributes_from_tracking_event_details_with_none_attributes():
+    tracking_event_details = TrackingEventDetails(value=5.0)
+    assert tracking_event_details.attributes == {}
+    assert tracking_event_details.value == 5.0