Merge pull request #109473 from openshift-cherrypick-robot/cherry-pick-109404-to-standalone-otel-docs-3.9

[standalone-otel-docs-3.9] OBSDOCS-2176: [Open Telemetry Phase 0] Perform Content Quality Assessment

Author: max-cx

modules/otel-collector-config-options.adoc

@@ -17,7 +17,8 @@ The OpenTelemetry Collector consists of five types of components that access tel
 
 You can define multiple instances of components in a custom resource YAML file. When configured, these components must be enabled through pipelines defined in the `spec.config.service` section of the YAML file. As a best practice, only enable the components that you need.
 
-.Example of the OpenTelemetry Collector custom resource file
+The following is an example of the OpenTelemetry Collector custom resource file:
+
 [source,yaml]
 ----
 apiVersion: opentelemetry.io/v1beta1
@@ -61,7 +62,8 @@ where:
 
 `service`:: If a component is configured but not defined in the `service` section, the component is not enabled.
 
-.Parameters used by the Operator to define the OpenTelemetry Collector
+The Operator uses the following parameters to define the OpenTelemetry Collector:
+
 [options="header"]
 [cols="l, a, a, a"]
 |===

modules/otel-collector-profile-signal.adoc

@@ -21,7 +21,8 @@ Profiling can target an application or operating system:
 
 * Using profiling to observe operating systems can provide insights into the infrastructure, system calls, kernel operations, and I/O wait times, and thus help in optimizing infrastructure for efficiency and cost savings.
 
-.OpenTelemetry Collector custom resource with the enabled Profile signal
+The following is an OpenTelemetry Collector custom resource with the enabled Profile signal:
+
 [source,yaml]
 ----
 apiVersion: opentelemetry.io/v1beta1

modules/otel-config-instrumentation.adoc

@@ -19,7 +19,8 @@ The {OTelOperator} only supports the injection mechanism of the instrumentation
 
 Instrumentation options are specified in an `Instrumentation` custom resource (CR).
 
-.Sample `Instrumentation` CR
+The following is a sample `Instrumentation` CR:
+
 [source,yaml]
 ----
 apiVersion: opentelemetry.io/v1alpha1
@@ -59,13 +60,13 @@ where:
 `dotnet.env`:: Required if endpoint is set to `:4317`.
 `go`:: Go auto-instrumentation uses protocol buffers over HTTP (HTTP/proto or HTTP/protobuf) by default.
 `go.env`:: Required if endpoint is set to `:4317`.
-
 +
 For more information about protocol buffers, see link:https://protobuf.dev/overview/[Overview] (Protocol Buffers Documentation).
 
 //[cols=",,",options="header",]
 
-.Parameters used by the Operator to define the instrumentation
+The Operator uses the following parameters to define the instrumentation:
+
 [options="header"]
 [cols="a, a, a"]
 |===
@@ -119,7 +120,8 @@ Depending on the programming language, environment variables might not work for
 
 |===
 
-.Default protocol for auto-instrumentation
+The following is the default protocol for auto-instrumentation:
+
 [options="header"]
 [cols="a, a"]
 |===
@@ -160,7 +162,8 @@ You can use the `instrumentation.opentelemetry.io/inject-sdk` annotation in the
 * `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`
 * `OTEL_EXPORTER_OTLP_CLIENT_KEY`
 
-.Values for the `instrumentation.opentelemetry.io/inject-sdk` annotation
+The `instrumentation.opentelemetry.io/inject-sdk` annotation accepts the following values:
+
 [cols="a, a"]
 |===
 | Value | Description
@@ -184,7 +187,8 @@ You can use the `instrumentation.opentelemetry.io/inject-sdk` annotation in the
 
 Although the `Instrumentation` custom resource supports setting up one or more exporters per signal, auto-instrumentation configures only the OTLP Exporter. So you must configure the endpoint to point to the OTLP Receiver on the Collector.
 
-.Sample exporter TLS CA configuration using a config map
+The following is a sample exporter TLS CA configuration using a config map:
+
 [source,yaml]
 ----
 apiVersion: opentelemetry.io/v1alpha1
@@ -205,7 +209,8 @@ where:
 `configMapName`:: Specifies the name of the config map. The config map must already exist in the namespace of the pod injecting the auto-instrumentation.
 `ca_file`:: Points to the CA certificate in the config map or the absolute path to the certificate if the certificate is already present in the workload file system.
 
-.Sample exporter mTLS configuration using a Secret
+The following is a sample exporter mTLS configuration using a Secret:
+
 [source,yaml]
 ----
 apiVersion: opentelemetry.io/v1alpha1
@@ -235,7 +240,8 @@ where:
 You can provide the CA certificate in a config map or Secret. If you provide it in both, the config map takes higher precedence than the Secret.
 ====
 
-.Example configuration for CA bundle injection by using a config map and `Instrumentation` CR
+The following is an example configuration for CA bundle injection by using a config map and `Instrumentation` CR:
+
 [source,yaml]
 ----
 apiVersion: v1
@@ -266,7 +272,8 @@ spec:
 :FeatureName: The Apache HTTP Server auto-instrumentation
 include::snippets/technology-preview.adoc[leveloffset=+1]
 
-.Parameters for the `+.spec.apacheHttpd+` field
+The `+.spec.apacheHttpd+` field uses the following parameters:
+
 [options="header"]
 [cols="a, a, a"]
 |===
@@ -298,7 +305,8 @@ include::snippets/technology-preview.adoc[leveloffset=+1]
 
 |===
 
-.The `PodSpec` annotation to enable injection
+The following is the `PodSpec` annotation to enable injection:
+
 [source,yaml]
 ----
 instrumentation.opentelemetry.io/inject-apache-httpd: "true"
@@ -333,7 +341,8 @@ By default, this feature injects unsupported, upstream instrumentation libraries
 
 For the .NET auto-instrumentation, the required `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable must be set if the endpoint of the exporters is set to `4317`. The .NET autoinstrumentation uses `http/proto` by default, and the telemetry data must be set to the `4318` port.
 
-.The `PodSpec` annotation to enable injection
+The following is the `PodSpec` annotation to enable injection:
+
 [source,yaml]
 ----
 instrumentation.opentelemetry.io/inject-dotnet: "true"
@@ -366,7 +375,8 @@ By default, this feature injects unsupported, upstream instrumentation libraries
 
 |===
 
-.The `PodSpec` annotation to enable injection
+The following is the `PodSpec` annotation to enable injection:
+
 [source,yaml]
 ----
 instrumentation.opentelemetry.io/inject-go: "true"
@@ -376,7 +386,8 @@ where:
 
 `otel-go-auto-target-exe`:: Sets the value for the required `OTEL_GO_AUTO_TARGET_EXE` environment variable.
 
-.Permissions required for the Go auto-instrumentation in the OpenShift cluster
+Go auto-instrumentation requires the following permissions in the OpenShift cluster:
+
 [source,yaml]
 ----
 apiVersion: security.openshift.io/v1
@@ -436,7 +447,8 @@ By default, this feature injects unsupported, upstream instrumentation libraries
 
 |===
 
-.The `PodSpec` annotation to enable injection
+The following is the `PodSpec` annotation to enable injection:
+
 [source,yaml]
 ----
 instrumentation.opentelemetry.io/inject-java: "true"
@@ -469,7 +481,8 @@ By default, this feature injects unsupported, upstream instrumentation libraries
 
 |===
 
-.The `PodSpec` annotations to enable injection
+The following `PodSpec` annotations enable injection:
+
 [source,yaml]
 ----
 instrumentation.opentelemetry.io/inject-nodejs: "true"
@@ -504,7 +517,8 @@ By default, this feature injects unsupported, upstream instrumentation libraries
 
 For Python auto-instrumentation, the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable must be set if the endpoint of the exporters is set to `4317`. Python auto-instrumentation uses `http/proto` by default, and the telemetry data must be set to the `4318` port.
 
-.The `PodSpec` annotation to enable injection
+The following is the `PodSpec` annotation to enable injection:
+
 [source,yaml]
 ----
 instrumentation.opentelemetry.io/inject-python: "true"
@@ -515,7 +529,8 @@ instrumentation.opentelemetry.io/inject-python: "true"
 
 The instrumentation is injected to the first container that is available by default according to the pod specification. You can also specify the target container names for injection.
 
-.Pod annotation
+This pod annotation is required:
+
 [source,yaml]
 ----
 instrumentation.opentelemetry.io/container-names: "<container_1>,<container_2>"
@@ -542,7 +557,8 @@ where:
 
 `container-names`:: You can inject instrumentation for only one language per container. For the list of supported `<application_language>` values, see the following table.
 
-.Supported values for the `<application_language>`
+The `<application_language>` parameter supports the following values:
+
 [options="header"]
 [cols="a, a"]
 |===

modules/otel-config-receive-metrics-monitoring-stack.adoc

@@ -9,7 +9,8 @@
 [role="_abstract"]
 A configured OpenTelemetry Collector custom resource (CR) can set up the Prometheus receiver to scrape metrics from the in-cluster monitoring stack.
 
-.Example of the OpenTelemetry Collector CR for scraping metrics from the in-cluster monitoring stack
+The following is an example of the OpenTelemetry Collector CR for scraping metrics from the in-cluster monitoring stack:
+
 [source,yaml]
 ----
 apiVersion: rbac.authorization.k8s.io/v1

modules/otel-config-send-metrics-monitoring-stack.adoc

@@ -9,7 +9,8 @@
 [role="_abstract"]
 You can configure the `OpenTelemetryCollector` custom resource (CR) to create a Prometheus `ServiceMonitor` CR or a `PodMonitor` CR for a sidecar deployment. A `ServiceMonitor` can scrape Collector's internal metrics endpoint and Prometheus exporter metrics endpoints.
 
-.Example of the OpenTelemetry Collector CR with the Prometheus exporter
+The following is an example of the OpenTelemetry Collector CR with the Prometheus exporter:
+
 [source,yaml]
 ----
 apiVersion: opentelemetry.io/v1beta1
@@ -52,7 +53,8 @@ Setting `enableMetrics` to `true` creates the following two `ServiceMonitor` ins
 
 Alternatively, a manually created Prometheus `PodMonitor` CR can provide fine control, for example removing duplicated labels added during Prometheus scraping.
 
-.Example of the `PodMonitor` CR that configures the monitoring stack to scrape the Collector metrics
+The following is an example of the `PodMonitor` CR that configures the monitoring stack to scrape the Collector metrics:
+
 [source,yaml]
 ----
 apiVersion: monitoring.coreos.com/v1

modules/otel-connectors-count-connector.adoc

@@ -22,7 +22,8 @@ The following are the default metric names:
 
 You can also expose custom metric names.
 
-.OpenTelemetry Collector custom resource (CR) with an enabled Count Connector
+The following is an OpenTelemetry Collector custom resource (CR) with an enabled Count Connector:
+
 [source,yaml]
 ----
 # ...
@@ -53,15 +54,15 @@ where:
 `exporters`:: Configures the Count Connector to receive spans as an exporter.
 `receivers`:: Configures the Count Connector to emit generated metrics as a receiver.
 
-+
 [TIP]
 ====
 If the Count Connector is not generating the expected metrics, you can check whether the OpenTelemetry Collector is receiving the expected spans, metrics, and logs, and whether the telemetry data flow through the Count Connector as expected. You can also use the Debug Exporter to inspect the incoming telemetry data.
 ====
 
 The Count Connector can count telemetry data according to defined conditions and expose those data as metrics when configured by using such fields as `spans`, `spanevents`, `metrics`, `datapoints`, or `logs`. See the next example.
 
-.Example OpenTelemetry Collector CR for the Count Connector to count spans by conditions
+The following is an example OpenTelemetry Collector CR for the Count Connector to count spans by conditions:
+
 [source,yaml]
 ----
 # ...
@@ -81,15 +82,15 @@ where:
 `spans`:: In this example, the exposed metric counts spans with the specified conditions.
 `<custom_metric_name>`:: You can specify a custom metric name such as `cluster.prod.event.count`.
 
-+
 [TIP]
 ====
 Write conditions correctly and follow the required syntax for attribute matching or telemetry field conditions. Improperly defined conditions are the most likely sources of errors.
 ====
 
 The Count Connector can count telemetry data according to defined attributes when configured by using such fields as `spans`, `spanevents`, `metrics`, `datapoints`, or `logs`. See the next example. The attribute keys are injected into the telemetry data. You must define a value for the `default_value` field for missing attributes.
 
-.Example OpenTelemetry Collector CR for the Count Connector to count logs by attributes
+The following is an example OpenTelemetry Collector CR for the Count Connector to count logs by attributes:
+
 [source,yaml]
 ----
 # ...

modules/otel-connectors-forward-connector.adoc

@@ -12,7 +12,8 @@ The Forward Connector merges two pipelines of the same type.
 :FeatureName: The Forward Connector
 include::snippets/technology-preview.adoc[]
 
-.OpenTelemetry Collector custom resource with an enabled Forward Connector
+The following is an OpenTelemetry Collector custom resource with an enabled Forward Connector:
+
 [source,yaml]
 ----
 # ...

modules/otel-connectors-routing-connector.adoc

@@ -13,7 +13,8 @@ The Routing Connector routes logs, metrics, and traces to specified pipelines ac
 include::snippets/technology-preview.adoc[]
 :!FeatureName:
 
-.OpenTelemetry Collector custom resource with an enabled Routing Connector
+The following is an OpenTelemetry Collector custom resource with an enabled Routing Connector:
+
 [source,yaml]
 ----
 # ...

modules/otel-connectors-span-metrics-connector.adoc

@@ -9,7 +9,8 @@
 [role="_abstract"]
 The Span Metrics Connector aggregates request, error, and duration (RED) OpenTelemetry metrics from span data.
 
-.OpenTelemetry Collector custom resource with an enabled Span Metrics Connector
+The following is an OpenTelemetry Collector custom resource with an enabled Span Metrics Connector:
+
 [source,yaml]
 ----
 # ...

modules/otel-exporters-aws-cloudwatch-exporter.adoc

@@ -13,7 +13,8 @@ The AWS CloudWatch Logs Exporter sends logs data to the Amazon CloudWatch Logs s
 include::snippets/technology-preview.adoc[]
 :!FeatureName:
 
-.OpenTelemetry Collector custom resource with the enabled AWS CloudWatch Logs Exporter
+The following is an OpenTelemetry Collector custom resource with the enabled AWS CloudWatch Logs Exporter:
+
 [source,yaml]
 ----
 # ...