feat: impact metrics docs (#356)

Author: sjaanus

README.md

@@ -320,6 +320,65 @@ UnleashConfig config = UnleashConfig.builder()
 
 This will then start using OkHttp instead of HttpURLConnection to send metrics.
 
+## Impact metrics
+
+Impact metrics are lightweight, application-level time-series metrics stored and visualized directly inside Unleash. They allow you to connect specific application data, such as request counts, error rates, or memory usage, to your feature flags and release plans.
+
+Use impact metrics to validate feature impact and automate your release process. For example, you can monitor usage patterns or performance to see if a feature is meeting its goals. By combining impact metrics with release templates, you can reduce manual release operations and automate milestone progression based on metric thresholds.
+
+The SDK automatically attaches the following context labels to your metrics: `appName`, `environment`, and `origin` (for example, `origin=sdk` or `origin=Edge`).
+
+### Counters
+
+Use counters for cumulative values that only increase, such as the total number of requests or errors.
+
+```java
+UnleashConfig config =
+        UnleashConfig.builder()
+                .appName("my-java-app")
+                .instanceId("instance-1")
+                .unleashAPI("https://YOUR-API-URL")
+                .apiKey("<YOUR_API_TOKEN>")
+                .build();
+
+Unleash unleash = new DefaultUnleash(config);
+
+unleash.getImpactMetrics()
+        .defineCounter("request_count", "Total number of HTTP requests processed");
+
+unleash.getImpactMetrics().incrementCounter("request_count");
+```
+
+### Gauges
+
+Use gauges for values that can go up and down, such as current memory usage or active thread count.
+
+```java
+unleash.getImpactMetrics()
+        .defineGauge("heap_memory_total", "Current heap memory usage in bytes");
+
+long currentHeap = Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory();
+
+unleash.getImpactMetrics().updateGauge("heap_memory_total", currentHeap);
+```
+
+### Histograms
+
+Use histograms to measure the distribution of values, such as request duration or response size. Unleash automatically calculates percentiles (p50, p95, p99).
+
+```java
+unleash.getImpactMetrics()
+        .defineHistogram("request_time_ms", "Time taken to process a request in milliseconds");
+
+long start = System.currentTimeMillis();
+// handleRequest();
+long duration = System.currentTimeMillis() - start;
+
+unleash.getImpactMetrics().observeHistogram("request_time_ms", duration);
+```
+
+Impact metrics are batched and sent on the same interval as regular SDK metrics. They are ingested via the regular metrics endpoint.
+
 ## Local backup
 By default unleash-client fetches the feature toggles from unleash-server every 10s, and stores the
 result in `unleash-repo.json` which is located in the `java.io.tmpdir` directory. This means that if