Lens metric trends

explore-analyze/visualize/lens.md

@@ -184,6 +184,54 @@ Color mapping works best with fields that have a reasonable number of distinct v
 
 When choosing colors, consider how they will appear in both light and dark themes. Use theme-aware neutral colors when you want to de-emphasize data.
 
+### Show trends in Metric charts [metric-trends]
+```{applies_to}
+stack: ga 9.1
+serverless: ga
+```
+
+When creating **Metric** visualizations with numeric data, you can add trend indicators that compare your primary metric to a secondary value. This feature displays colored badges with directional arrows to help you quickly identify whether values are increasing, decreasing, or staying the same.
+
+| Without trend | With trend |
+|--------|-------|
+| ![Secondary metric before comparison](../images/secondary_metric_before_compare.png "title =70%") | ![Secondary metric after comparison](../images/secondary_metric_after_compare.png "title =70%") |
+
+To add trend indicators to your metric visualization:
+
+1. Create a **Metric** visualization with a numeric primary metric.
+2. Add a secondary metric that represents the comparison value.
+
+    ::::{tip}
+    Use the `shift` parameter in formulas to compare current values against historical data. For example, if your primary metric is counting orders (based on an `order_id` field) for the current week, you can use the `count(order_id, shift='1w')` formula to compare this week's count of orders to last week's count.
+    ::::
+
+3. In the secondary metric configuration, look for the **Color by value** option. The possible choices are:
+   * **None** — No trend indicators (default)
+   * **Static** — Shows the secondary metric as a badge with a single color that you select
+   * **Dynamic** — Enables both color coding and directional icons based on the comparison
+
+4. Select **Dynamic** coloring. More options appear.
+
+5. Choose a **Color palette** that matches how you'd like to represent the comparison.
+
+6. Configure the **Display** option:
+   * **Icon** — Shows only directional arrows: ↑ for increase, ↓ for decrease, = for no change
+   * **Value** — Shows only the secondary metric value
+   * **Both** — Shows both the icon and value (default)
+
+7. The secondary metric does not automatically compare with the primary metric. Define the value to **Compare to**:
+   * **Static value** — Compares against a fixed baseline value that you specify
+   * **Primary metric** — Compares the secondary metric directly against the primary metric. This option is only available when the primary metric is numeric. 
+
+     When you select this option, the secondary metric is automatically updated:
+
+       * The secondary metric label changes to **Difference**. You can change this by editing the **Prefix** option of the metric.
+       * If you chose a **Display** option that shows a value, the secondary metric value is automatically updated to show the difference compared to the primary metric.
+
+7. Apply your changes. 
+
+The metric visualization is updated and now shows the secondary metric as a comparison with a trend indicator.
+
 
 ### Create visualizations with keyboard navigation [drag-and-drop-keyboard-navigation]