From 7d987dfdca9c97473e39edaaa5b59a3c44124935 Mon Sep 17 00:00:00 2001
From: Paulin Todev <paulin.todev@gmail.com>
Date: Wed, 10 Jan 2024 20:03:33 +0000
Subject: [PATCH] Clarify usage of resource_to_telemetry_conversion (#6076)

* Clarify usage of resource_to_telemetry_conversion

* Apply suggestions from code review

Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>

---------

Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com>
---
 .../components/otelcol.exporter.prometheus.md | 62 +++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/docs/sources/flow/reference/components/otelcol.exporter.prometheus.md b/docs/sources/flow/reference/components/otelcol.exporter.prometheus.md
index 3008f22f4353..4285f34cc799 100644
--- a/docs/sources/flow/reference/components/otelcol.exporter.prometheus.md
+++ b/docs/sources/flow/reference/components/otelcol.exporter.prometheus.md
@@ -58,6 +58,18 @@ When `include_scope_labels` is `true`  the `otel_scope_name` and
 
 When `include_target_info` is true, OpenTelemetry Collector resources are converted into `target_info` metrics.
 
+{{% admonition type="note" %}}
+
+OTLP metrics can have a lot of resource attributes. 
+Setting `resource_to_telemetry_conversion` to `true` would convert all of them to Prometheus labels, which may not be what you want.
+Instead of using `resource_to_telemetry_conversion`, most users need to use `otelcol.processor.transform` 
+to convert OTLP resource attributes to OTLP metric datapoint attributes before using `otelcol.exporter.prometheus`. 
+See [Creating Prometheus labels from OTLP resource attributes][] for an example.
+
+[Creating Prometheus labels from OTLP resource attributes]: #creating-prometheus-labels-from-otlp-resource-attributes
+
+{{% /admonition %}}
+
 ## Exported fields
 
 The following fields are exported and can be referenced by other components:
@@ -87,6 +99,8 @@ information.
 
 ## Example
 
+## Basic usage
+
 This example accepts metrics over OTLP and forwards it using
 `prometheus.remote_write`:
 
@@ -109,6 +123,54 @@ prometheus.remote_write "mimir" {
   }
 }
 ```
+
+## Create Prometheus labels from OTLP resource attributes
+
+This example uses `otelcol.processor.transform` to add extra `key1` and `key2` OTLP metric datapoint attributes from the
+`key1` and `key2` OTLP resource attributes. 
+
+`otelcol.exporter.prometheus` then converts `key1` and `key2` to Prometheus labels along with any other OTLP metric datapoint attributes.
+
+This avoids the need to set `resource_to_telemetry_conversion` to `true`,
+which could have created too many unnecessary metric labels.
+
+```river
+otelcol.receiver.otlp "default" {
+  grpc {}
+
+  output {
+    metrics = [otelcol.processor.transform.default.input]
+  }
+}
+
+otelcol.processor.transform "default" {
+  error_mode = "ignore"
+
+  metric_statements {
+    context = "datapoint"
+
+    statements = [
+      `set(attributes["key1"], resource.attributes["key1"])`,
+      `set(attributes["key2"], resource.attributes["key2"])`,
+    ]
+  }
+
+  output {
+    metrics = [otelcol.exporter.prometheus.default.input]
+  }
+}
+
+otelcol.exporter.prometheus "default" {
+  forward_to = [prometheus.remote_write.mimir.receiver]
+}
+
+prometheus.remote_write "mimir" {
+  endpoint {
+    url = "http://mimir:9009/api/v1/push"
+  }
+}
+```
+
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 
 ## Compatible components