Merge pull request #82621 from iblancasa/TRACING-4456

TRACING-4456: improve documentation about zPages extension

Author: JoeAldinger

observability/otel/otel-collector/otel-collector-extensions.adoc

@@ -425,9 +425,8 @@ include::snippets/technology-preview.adoc[]
 [id="zpages-extension_{context}"]
 == zPages Extension
 
-The zPages Extension provides an HTTP endpoint for extensions that serve zPages. At the endpoint, this extension serves live data for debugging instrumented components. All core exporters and receivers provide some zPages instrumentation.
+The zPages Extension provides an HTTP endpoint that serves live data for debugging instrumented components in real time. You can use this extension for in-process diagnostics and insights into traces and metrics without relying on an external backend. With this extension, you can monitor and troubleshoot the behavior of the OpenTelemetry Collector and related components by watching the diagnostic information at the provided endpoint.
 
-zPages are useful for in-process diagnostics without having to depend on a back end to examine traces or metrics.
 
 :FeatureName: The zPages Extension
 include::snippets/technology-preview.adoc[]
@@ -446,18 +445,38 @@ include::snippets/technology-preview.adoc[]
         protocols:
           http: {}
     exporters:
-      otlp:
+      debug:
 
     service:
       extensions: [zpages]
       pipelines:
         traces:
           receivers: [otlp]
-          exporters: [otlp]
+          exporters: [debug]
 # ...
 ----
 
-<1> Specifies the HTTP endpoint that serves zPages. Use `localhost:` to make it available only locally, or `":"` to make it available on all network interfaces. The default is `localhost:55679`.
+<1> Specifies the HTTP endpoint for serving the zPages extension. The default is `localhost:55679`.
+
+[IMPORTANT]
+====
+Accessing the HTTP endpoint requires port-forwarding because the {OTELOperator} does not expose this route.
+
+You can enable port-forwarding by running the following `oc` command:
+
+[source,terminal]
+----
+$ oc port-forward pod/$(oc get pod -l app.kubernetes.io/name=instance-collector -o=jsonpath='{.items[0].metadata.name}') 55679
+----
+====
+
+The Collector provides the following zPages for diagnostics:
+
+*ServiceZ*:: Shows an overview of the Collector services and links to the following zPages: *PipelineZ*, *ExtensionZ*, and *FeatureZ*. This page also displays information about the build version and runtime. An example of this page's URL is `http://localhost:55679/debug/servicez`.
+*PipelineZ*:: Shows detailed information about the active pipelines in the Collector. This page displays the pipeline type, whether data are modified, and the associated receivers, processors, and exporters for each pipeline. An example of this page's URL is `http://localhost:55679/debug/pipelinez`.
+*ExtensionZ*:: Shows the currently active extensions in the Collector. An example of this page's URL is `http://localhost:55679/debug/extensionz`.
+*FeatureZ*:: Shows the feature gates enabled in the Collector along with their status and description. An example of this page's URL is `http://localhost:55679/debug/featurez`.
+*TraceZ*:: Shows spans categorized by latency. Available time ranges include 0 µs, 10 µs, 100 µs, 1 ms, 10 ms, 100 ms, 1 s, 10 s, 1 m. This page also allows for quick inspection of error samples. An example of this page's URL is `http://localhost:55679/debug/tracez`.
 
 [role="_additional-resources"]
 [id="additional-resources_otel-collector-extensions_{context}"]