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 <[email protected]>

---------

Co-authored-by: Clayton Cornell <[email protected]>

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" >}}