Docs10108/composite queries

config/_default/menus/main.en.yaml

@@ -1852,16 +1852,21 @@ menu:
       parent: metrics_top_level
       identifier: metrics_nested_queries
       weight: 10
+    - name: Composite Metrics Queries
+      url: metrics/composite_metrics_queries
+      parent: metrics_top_level
+      identifier: composite_metrics_queries
+      weight: 11
     - name: Metrics Without Limits™
       identifier: metrics_without_limits
       url: metrics/metrics-without-limits/
       parent: metrics_top_level
-      weight: 11
+      weight: 12
     - name: Guides
       url: metrics/guide
       parent: metrics_top_level
       identifier: metrics_guide
-      weight: 12
+      weight: 13
     - name: Watchdog
       url: watchdog/
       identifier: watchdog_top_level

content/en/metrics/composite_metrics_queries.md

@@ -0,0 +1,38 @@
+---
+title: Composite Metrics Queries
+further_reading:
+- link: "/reference_tables/"
+  tag: "Documentation"
+  text: "Reference Tables"
+---
+
+## Overview
+
+Composite metrics queries enhance your monitoring and analysis capabilities by allowing dynamic tagging of metrics at query time. This simplifies the process of adding new tags to your metrics, and requires no code changes. Use composite metrics queries to enable more meaningful and actionable insights from your metric data.
+
+Using composite metrics queries, you can accomplish the following:
+
+- **Build context-rich dashboards**. Use [Reference Tables][1] to append more contextual tags such as `team` or `organization` to your metrics.
+- **Simplify troubleshooting**. Alias opaque tag values (for example, IDs or codes) to human-readable values, reducing cognitive effort and resolution time.
+
+{{< img src="metrics/nested_queries/composite_metrics_queries/composite_metric_query_example.mp4" alt="How to configure composite metrics queries in the UI" video=true style="width:100%" >}}
+
+## Setup
+
+1. Create any metric query with [space aggregation][2] (one or more tags are selected to group by)
+2. Select the **Join** button (next to the **Formulas** button) as shown below:
+
+{{< img src="metrics/nested_queries/composite_metrics_queries/reference_table_join.png" alt="The Join with Reference Table option in a metrics query" style="width:100%" >}}
+
+3. Specify the type of join and the reference table you want to join your metrics query to 
+4. Define the join condition with the existing tag from your query (for example, `team`) and the column in your reference table to be used for the join
+5. Select any columns of that reference table that you want to represent the aliased or new tags to be added to your existing query
+
+{{< img src="metrics/nested_queries/composite_metrics_queries/reference_table_example.png" alt="A metrics query configured to join with a reference table" style="width:100%" >}}
+
+## Further reading
+
+{{< partial name="whats-next/whats-next.html" >}}
+
+[1]: /reference_tables/
+[2]: /metrics/#space-aggregation