From e7b95cf1b2e5f76afc1d68129db0e3d637e0f91c Mon Sep 17 00:00:00 2001
From: Paulin Todev <paulin.todev@gmail.com>
Date: Fri, 16 Feb 2024 15:20:05 +0000
Subject: [PATCH] In `otelcol.auth.headers`, clarify usage of `from_context`
 (#6373)

* Clarify usage of from_context

* 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.auth.headers.md        | 41 ++++++++++++++++---
 1 file changed, 35 insertions(+), 6 deletions(-)

diff --git a/docs/sources/flow/reference/components/otelcol.auth.headers.md b/docs/sources/flow/reference/components/otelcol.auth.headers.md
index bd93a9045e31..6b70a021de35 100644
--- a/docs/sources/flow/reference/components/otelcol.auth.headers.md
+++ b/docs/sources/flow/reference/components/otelcol.auth.headers.md
@@ -70,9 +70,12 @@ Exactly one of `value` or `from_context` must be provided for each `header`
 block.
 
 The `value` attribute sets the value of the header directly.
+Alternatively, `from_context` can be used to dynamically retrieve the header value from request metadata.
 
-Alternatively, `from_context` can be used to dynamically retrieve the header
-value from request metadata.
+For `from_context` to work, other components in the pipeline also need to be configured appropriately:
+* If an `otelcol.processor.batch` is present in the pipeline, it must be configured to preserve client metadata. 
+  Do this by adding the value that `from_context` needs to the `metadata_keys` of the batch processor.
+* `otelcol` receivers must be configured with `include_metadata` set to `true` so that metadata keys are available to the pipeline.
 
 ## Exported fields
 
@@ -96,10 +99,29 @@ configuration.
 This example configures [otelcol.exporter.otlp][] to use custom headers:
 
 ```river
-otelcol.exporter.otlp "example" {
-  client {
-    endpoint = "my-otlp-grpc-server:4317"
-    auth     = otelcol.auth.headers.creds.handler
+otelcol.receiver.otlp "default" {
+  http {
+    include_metadata = true
+  }
+  grpc {
+    include_metadata = true
+  }
+
+  output {
+    metrics = [otelcol.processor.batch.default.input]
+    logs    = [otelcol.processor.batch.default.input]
+    traces  = [otelcol.processor.batch.default.input]
+  }
+}
+
+otelcol.processor.batch "default" {
+  // Preserve the tenant_id metadata.
+  metadata_keys = ["tenant_id"]
+
+  output {
+    metrics = [otelcol.exporter.otlp.production.input]
+    logs    = [otelcol.exporter.otlp.production.input]
+    traces  = [otelcol.exporter.otlp.production.input]
   }
 }
 
@@ -114,6 +136,13 @@ otelcol.auth.headers "creds" {
     value = "user_id"
   }
 }
+
+otelcol.exporter.otlp "production" {
+  client {
+    endpoint = env("OTLP_SERVER_ENDPOINT")
+    auth     = otelcol.auth.headers.creds.handler
+  }
+}
 ```
 
 [otelcol.exporter.otlp]: {{< relref "./otelcol.exporter.otlp.md" >}}