docs: add event tracking documentation for local resolve providers (#545)

Co-authored-by: vahidlazio <vahidlazio@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: vahidlazio

README.md

@@ -18,7 +18,8 @@ The tools and SDKs published for direct usage:
 
 Underlying building blocks:
 - `confidence-resolver`: Core resolver crate
-- `wasm` and `wasm-msg`: WASM resolver with communication contract towards the hosting environment 
+- `confidence-event-engine`: Event batching engine compiled to WASM (shared by all providers for `track()` support)
+- `wasm` and `wasm-msg`: WASM resolver with communication contract towards the hosting environment
 - `data`: Sample local development data (e.g., resolver state)
 
 

openfeature-provider/INTEGRATION_GUIDE.md

@@ -6,6 +6,7 @@ For language-specific installation and quick start instructions, see your provid
 - [Go Provider](go/README.md)
 - [Java Provider](java/README.md)
 - [JavaScript Provider](js/README.md)
+- [Python Provider](python/README.md)
 - [Ruby Provider](ruby/README.md)
 
 ---
@@ -15,8 +16,9 @@ For language-specific installation and quick start instructions, see your provid
 1. [Getting Your Credentials](#getting-your-credentials)
 2. [Encryption](#encryption)
 3. [Error Handling](#error-handling)
-4. [Sticky Assignments](#sticky-assignments)
-5. [Deferred Apply and Resolve Token Security](#deferred-apply-and-resolve-token-security)
+4. [Event Tracking](#event-tracking)
+5. [Sticky Assignments](#sticky-assignments)
+6. [Deferred Apply and Resolve Token Security](#deferred-apply-and-resolve-token-security)
 
 ---
 
@@ -143,6 +145,52 @@ For debugging, use the `details` methods to get error information:
 
 ---
 
+## Event Tracking
+
+All local-resolve providers support the [OpenFeature tracking API](https://openfeature.dev/specification/sections/tracking), enabling you to send custom events to the [Confidence events backend](https://confidence.spotify.com/docs). Events are batched inside a shared WebAssembly engine and flushed periodically alongside flag logs — no additional configuration is required.
+
+### How It Works
+
+1. You call `track()` on the OpenFeature client with an event name, optional evaluation context, and optional tracking details (a numeric `value` and arbitrary custom data).
+2. The event is queued inside the WASM event engine.
+3. A background flush publishes batches to the Confidence events service at the same interval as flag log flushing.
+4. On provider shutdown, pending events are drained (up to 100 batches).
+
+### Delivery Guarantees
+
+Events are delivered **at-most-once, best-effort**. Once a batch is flushed from the WASM buffer, a failed publish drops it — there is no re-queue or persistence. This matches the flag-log path. Transient failures are absorbed by transport-level retries (gRPC retry policy or fetch-layer retries), and sustained failures are surfaced via periodic warning logs rather than per-failure noise.
+
+On shutdown, each provider drains pending events on a best-effort basis (up to 100 batches, with a timeout). Events buffered when the process is killed uncleanly (e.g. `SIGKILL`) are lost.
+
+### Event Name Mapping
+
+You pass bare event names (e.g. `"checkout_completed"`). The WASM engine automatically prepends the `eventDefinitions/` prefix, so the event arrives at the Confidence backend as `eventDefinitions/checkout_completed`. This matches the [event definition](https://confidence.spotify.com/docs) resource naming in Confidence — you do not need to include the prefix yourself.
+
+### Payload Mapping
+
+The event payload is built by merging inputs in this order:
+
+1. **`data`** — your custom key-value fields from tracking details
+2. **`value`** — the numeric value from tracking details (overwrites a same-named key from `data`)
+3. **`context`** — the evaluation context (overwrites same-named keys from `data` and `value`)
+
+`value` and `context` are reserved keys. If your custom data contains a key named `"value"` or `"context"`, it will be overwritten.
+
+### Known Provider Differences
+
+**Go cannot distinguish `value: 0` from an unset value.** Go's `TrackingEventDetails` stores `value` as a plain `float64` with no "is set" flag. The Go provider treats `0` as unset and omits it to avoid attaching a spurious `value: 0` to every event. Java (`Optional<Number>`), JavaScript (`number | undefined`), and Python (`Optional[float]`) can distinguish them and forward an explicit `0` correctly. If you need to record a zero-valued event from Go, put it in the custom data instead.
+
+### Language-Specific Examples
+
+See your provider's README for usage examples:
+
+- [JavaScript](js/README.md#event-tracking)
+- [Java](java/README.md#event-tracking)
+- [Go](go/README.md#event-tracking)
+- [Python](python/README.md#event-tracking)
+
+---
+
 ## Sticky Assignments
 
 Confidence provides **sticky** flag assignments to ensure users receive consistent variant assignments across evaluations. It can be used for two things:
@@ -225,6 +273,7 @@ The provider only needs to see the original token at apply time — anything you
   - [Go Provider](go/README.md)
   - [Java Provider](java/README.md)
   - [JavaScript Provider](js/README.md)
+  - [Python Provider](python/README.md)
   - [Ruby Provider](ruby/README.md)
 - [Root Repository README](../README.md)
 - [Sticky Assignments Technical Guide](../STICKY_ASSIGNMENTS.md)

openfeature-provider/go/README.md

@@ -10,6 +10,7 @@ A high-performance OpenFeature provider for [Confidence](https://confidence.spot
 - **Low Latency**: No network calls during flag evaluation
 - **Automatic Sync**: Periodically syncs flag configurations from Confidence
 - **Exposure Logging**: Fully supported exposure logging and resolve analytics
+- **[Event Tracking](#event-tracking)**: Send custom events via the OpenFeature `Track()` API
 - **OpenFeature Compatible**: Works with the standard OpenFeature Go SDK
 
 ## Installation
@@ -563,6 +564,38 @@ The provider logs at different levels: `Debug` (flag resolution details), `Info`
 
 The shutdown respects the context timeout you provide.
 
+## Event Tracking
+
+The provider supports the [OpenFeature tracking API](https://openfeature.dev/specification/sections/tracking) for sending custom events to the Confidence events backend. Event tracking is automatically enabled when using `NewProvider` — no configuration needed.
+
+**📖 See the [Integration Guide: Event Tracking](../INTEGRATION_GUIDE.md#event-tracking)** for delivery guarantees, payload mapping rules, and cross-provider differences.
+
+### Usage
+
+```go
+client := openfeature.NewClient("my-app")
+
+evalCtx := openfeature.NewEvaluationContext("user-123", map[string]interface{}{
+    "country": "US",
+})
+
+// Track a simple event
+client.Track(ctx, "checkout_completed", evalCtx, openfeature.NewTrackingEventDetails(0))
+
+// Track with a numeric value
+client.Track(ctx, "purchase", evalCtx, openfeature.NewTrackingEventDetails(49.99))
+
+// Track with custom data
+details := openfeature.NewTrackingEventDetails(1)
+details.Add("sku", "ABC-123")
+details.Add("category", "electronics")
+client.Track(ctx, "item_added", evalCtx, details)
+```
+
+Events are batched internally and flushed to the Confidence events service at the same interval as flag logs (configurable via `LogPollInterval`). On shutdown, pending events are drained on a best-effort basis (up to 100 batches within a 3-second timeout).
+
+> **Note:** Go cannot distinguish `value: 0` from an unset value. The provider treats `0` as unset and omits it. If you need to record a zero-valued event, put it in the custom data instead of `value`. See the [Integration Guide](../INTEGRATION_GUIDE.md#known-provider-differences) for details.
+
 ## Advanced: Controlling Exposure Events
 
 By default, every flag evaluation records an exposure event (apply). Only disable this for exceptional cases where this provider must not collect exposures at all.

openfeature-provider/java/README.md

@@ -10,6 +10,7 @@ A high-performance OpenFeature provider for [Confidence](https://confidence.spot
 - **Low Latency**: No network calls during flag evaluation
 - **Automatic Sync**: Periodically syncs flag configurations from Confidence
 - **Exposure Logging**: Fully supported exposure logging (and other resolve analytics)
+- **[Event Tracking](#event-tracking)**: Send custom events via the OpenFeature `track()` API
 - **OpenFeature Compatible**: Works with the standard OpenFeature SDK
 - **HTTP Proxy Service**: Proxy requests from client SDKs through your backend for enhanced control
 
@@ -401,6 +402,33 @@ const confidence = Confidence.create({
 });
 ```
 
+## Event Tracking
+
+The provider supports the [OpenFeature tracking API](https://openfeature.dev/specification/sections/tracking) for sending custom events to the Confidence events backend. Event tracking is automatically enabled — no configuration needed.
+
+**📖 See the [Integration Guide: Event Tracking](../INTEGRATION_GUIDE.md#event-tracking)** for delivery guarantees, payload mapping rules, and cross-provider differences.
+
+### Usage
+
+```java
+Client client = OpenFeatureAPI.getInstance().getClient();
+
+// Track a simple event
+MutableContext ctx = new MutableContext("user-123");
+client.track("checkout_completed", ctx);
+
+// Track with a numeric value
+client.track("purchase", ctx, new MutableTrackingEventDetails(49.99f));
+
+// Track with custom data
+MutableTrackingEventDetails details = new MutableTrackingEventDetails(1.0f);
+details.add("sku", "ABC-123");
+details.add("category", "electronics");
+client.track("item_added", ctx, details);
+```
+
+Events are batched internally and flushed to the Confidence events service every 15 seconds. On shutdown, pending events are drained on a best-effort basis (up to 100 batches within a 5-second grace period).
+
 ## Advanced: Controlling Exposure Events
 
 By default, every flag evaluation records an exposure event (apply). Only disable this for exceptional cases where this provider must not collect exposures at all.

openfeature-provider/js/README.md

@@ -6,6 +6,7 @@ OpenFeature provider for the Spotify Confidence resolver (local mode, powered by
 
 - Local flag evaluation via WASM (no per-eval network calls)
 - Automatic state refresh and batched flag log flushing
+- [Event tracking](#event-tracking) via the OpenFeature `track()` API
 - Pluggable `fetch` with retries, timeouts and routing
 - Optional logging using `debug`
 - **[React integration](./README-REACT.md)** for Next.js with Server Components
@@ -361,6 +362,35 @@ yarn add debug
 
 ---
 
+## Event Tracking
+
+The provider supports the [OpenFeature tracking API](https://openfeature.dev/specification/sections/tracking) for sending custom events to the Confidence events backend. Event tracking is automatically enabled — no configuration needed.
+
+**📖 See the [Integration Guide: Event Tracking](../INTEGRATION_GUIDE.md#event-tracking)** for delivery guarantees, payload mapping rules, and cross-provider differences.
+
+### Usage
+
+```typescript
+const client = OpenFeature.getClient();
+
+// Track a simple event
+client.track('checkout_completed', { targetingKey: 'user-123' });
+
+// Track with a numeric value
+client.track('purchase', { targetingKey: 'user-123' }, { value: 49.99 });
+
+// Track with custom data
+client.track('item_added', { targetingKey: 'user-123' }, {
+  value: 1,
+  sku: 'ABC-123',
+  category: 'electronics',
+});
+```
+
+Events are batched internally and flushed to the Confidence events service at the same interval as flag logs (configurable via `flushInterval`). On shutdown (`onClose()`), pending events are drained on a best-effort basis (up to 100 batches).
+
+---
+
 ## Advanced: Controlling Exposure Events
 
 By default, every flag evaluation records an exposure event (apply). Only disable this for exceptional cases where this provider must not collect exposures at all.

openfeature-provider/python/README.md

@@ -10,6 +10,7 @@ A high-performance OpenFeature provider for [Confidence](https://confidence.spot
 - **Low Latency**: No network calls during flag evaluation
 - **Automatic Sync**: Periodically syncs flag configurations from Confidence
 - **Exposure Logging**: Fully supported exposure logging (and other resolve analytics)
+- **[Event Tracking](#event-tracking)**: Send custom events via the OpenFeature `track()` API
 - **OpenFeature Compatible**: Works with the standard OpenFeature SDK
 
 ## Requirements
@@ -254,6 +255,37 @@ import logging
 logging.getLogger("confidence").setLevel(logging.DEBUG)
 ```
 
+## Event Tracking
+
+The provider supports the [OpenFeature tracking API](https://openfeature.dev/specification/sections/tracking) for sending custom events to the Confidence events backend. Event tracking is automatically enabled — no configuration needed.
+
+**📖 See the [Integration Guide: Event Tracking](../INTEGRATION_GUIDE.md#event-tracking)** for delivery guarantees, payload mapping rules, and cross-provider differences.
+
+### Usage
+
+```python
+client = api.get_client()
+
+context = EvaluationContext(
+    targeting_key="user-123",
+    attributes={"country": "US"},
+)
+
+# Track a simple event
+client.track("checkout_completed", context)
+
+# Track with a numeric value
+client.track("purchase", context, TrackingEventDetails(value=49.99))
+
+# Track with custom data
+client.track("item_added", context, TrackingEventDetails(
+    value=1,
+    attributes={"sku": "ABC-123", "category": "electronics"},
+))
+```
+
+Events are batched internally and flushed to the Confidence events service at the same interval as flag logs (configurable via `log_poll_interval`). On shutdown, pending events are drained on a best-effort basis (up to 100 batches).
+
 ## Advanced: Controlling Exposure Events
 
 By default, every flag evaluation records an exposure event (apply). Only disable this for exceptional cases where this provider must not collect exposures at all.