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,24 @@ 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:
+ details = {}
+ value = None
+ if tracking_event_details:
+ details = tracking_event_details.attributes
+ value = tracking_event_details.value
+ 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