Events in README

README.md

@@ -42,15 +42,6 @@ The provider is instantiated using a client token that is configured in the Conf
 management API. After that all interaction with the feature flags happens using the OpenFeature client APIs. 
 
 ```java
-package com.spotify.confidence.openfeature;
-
-import com.spotify.confidence.ConfidenceFeatureProvider;
-import dev.openfeature.sdk.Client;
-import dev.openfeature.sdk.MutableContext;
-import dev.openfeature.sdk.OpenFeatureAPI;
-import dev.openfeature.sdk.Value;
-import java.util.Map;
-
 public final class ResolveFlags {
 
   public static final String CLIENT_TOKEN = "<>";
@@ -69,3 +60,42 @@ public final class ResolveFlags {
   }
 }
 ```
+
+## Metrics emission (EXPERIMENTAL)
+
+Confidence offers APIs to collect metrics from your application in the form of `EVENTS`.
+
+The experimental `Confidence` interface allows to both:
+- Configure the OpenFeature Provider for flag resolves
+- Emit events
+
+Usage example:
+
+```java
+import com.spotify.confidence.ConfidenceValue;
+
+public final class ResolveFlags {
+
+  public static final String CLIENT_TOKEN = "<>";
+
+  public static void main(String[] args) {
+    final Confidence confidence = Confidence.builder(CLIENT_TOKEN).build();
+    // Flags are operated via the same OpenFeature Client APIs
+    OpenFeatureAPI.getInstance().setProvider(new ConfidenceFeatureProvider(confidence));
+
+    // Additionally, events can be emitted
+    confidence.send("my-event", ConfidenceValue.of("event-value"));
+  }
+}
+```
+The `send()` API currently supports:
+- Setting a custom event's payload with all the Confidence-supported types via the `ConfidenceValue` interfaces
+- Automatically including the OpenFeature's `Evaluation Context` detected at the time `send()` is called
+  - _Note: this only considers the global Evaluation Context set at the OpenFeatureAPI level_
+- Setting a shared `Event Context` that is going to be appended to each event:
+
+```java
+    final Confidence confidenceWithContext = Confidence.withContext(ConfidenceValue.of("context-value"));
+    confidenceWithContext.send("my-event", ConfidenceValue.of("event-value"));
+```
+The "my-event" event in the example above will contain fields for "event-value", "context-value" and the Evaluation Context data set via `OpenFeatureAPI.getInstance().setEvaluationContext(...)`.