Merge pull request #20270 from mburke5678/logging-sergey-comments

mburke5678 · web-flow · commit e00f6e7caff2 · 2020-03-17T15:59:24.000-04:00
Edits suggested by Sergey Yedrikov
diff --git a/_topic_map.yml b/_topic_map.yml
@@ -994,7 +994,7 @@ Topics:
 - Name: Viewing cluster logs
   File: cluster-logging-viewing
   Distros: openshift-enterprise,openshift-webscale,openshift-origin
-- Name: Viewing the Kibana interface
+- Name: Viewing cluster logs using Kibana
   File: cluster-logging-kibana-interface
 - Name: Configuring your cluster logging deployment
   Dir: config
diff --git a/_unused_topics/cluster-logging-fluentd-json.adoc b/_unused_topics/cluster-logging-fluentd-json.adoc
@@ -16,7 +16,7 @@ Enabling this feature comes with risks, including:
 
 * Possible log loss due to Elasticsearch rejecting documents due to inconsistent type mappings.
 * Potential buffer storage leak caused by rejected message cycling.
-* Overwrite of data for field with same names.
+* Overwriting data for fields with the same name.
 
 The features in this topic should be used by only experienced Fluentd and Elasticsearch users.
 ====
diff --git a/logging/cluster-logging-deploying-about.adoc b/logging/cluster-logging-deploying-about.adoc
@@ -5,7 +5,7 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-Before installing cluster logging into your cluster, review the following sections.
+Before installing cluster logging into your {product-title} cluster, review the following sections.
 
 // The following include statements pull in the module files that comprise
 // the assembly. Include any combination of concept, procedure, or reference
diff --git a/logging/cluster-logging-kibana-interface.adoc b/logging/cluster-logging-kibana-interface.adoc
@@ -1,11 +1,11 @@
 :context: cluster-logging-kibana-interface
 [id="cluster-logging-kibana-interface"]
-= Viewing the Kibana console
+= Viewing cluster logs using Kibana
 include::modules/common-attributes.adoc[]
 
 toc::[]
 
-The cluster logging installation deploys the Kibana console. 
+The cluster logging installation deploys the Kibana web console. 
 
 
 // The following include statements pull in the module files that comprise
diff --git a/logging/cluster-logging-viewing.adoc b/logging/cluster-logging-viewing.adoc
@@ -5,7 +5,7 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-You can view cluster logs in the CLI or {product-title} web console. 
+You can view {product-title} cluster logs in the CLI or {product-title} web console. 
 
 // The following include statements pull in the module files that comprise
 // the assembly. Include any combination of concept, procedure, or reference
diff --git a/logging/cluster-logging.adoc b/logging/cluster-logging.adoc
@@ -8,8 +8,9 @@ toc::[]
 
 
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
-{product-title} cluster logging aggregates all of the logs from your {product-title} cluster, 
-such as node system logs, application container logs, and so forth.
+As an {product-title} cluster administrator, you can deploy cluster logging to
+aggregate all the logs from your {product-title} cluster, such as node system logs, application container logs,
+and so forth.
 endif::[]
 
 ifdef::openshift-dedicated[]
diff --git a/logging/config/cluster-logging-collector.adoc b/logging/config/cluster-logging-collector.adoc
@@ -5,7 +5,7 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-{product-title} uses Fluentd to collect operations and application logs from your cluster which {product-title} enriches with Kubernetes Pod and Namespace metadata.
+{product-title} uses Fluentd to collect operations and application logs from your cluster and enriches the data with Kubernetes Pod and Namespace metadata.
 
 You can configure log rotation, log location, use an external log aggregator, and make other configurations for the log collector.
 
diff --git a/logging/config/cluster-logging-configuring-about.adoc b/logging/config/cluster-logging-configuring-about.adoc
@@ -5,7 +5,7 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-After installing cluster logging into your cluster, you can make the following configurations.
+After installing cluster logging into your {product-title} cluster, you can make the following configurations.
 
 [NOTE]
 ====
diff --git a/logging/config/cluster-logging-curator.adoc b/logging/config/cluster-logging-curator.adoc
@@ -6,7 +6,7 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 The Elasticsearch Curator tool performs scheduled maintenance operations
-on a global and/or on a per-project basis. Curator performs actions daily based on its configuration.
+on a global and/or on a per-project basis. Curator performs actions based on its configuration.
 
 The Cluster Logging Operator installs Curator and its configuration.
 You can configure the Curator link:https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs[cron schedule] using the Cluster Logging Custom Resource and further
diff --git a/logging/config/cluster-logging-elasticsearch.adoc b/logging/config/cluster-logging-elasticsearch.adoc
@@ -7,14 +7,11 @@ toc::[]
 
 {product-title} uses Elasticsearch (ES) to store and organize the log data.
 
-You can configure storage for your Elasticsearch cluster, and 
-define how shards are replicated across data nodes in the cluster, from full replication to no replication.
+Some of the modifications you can make to your Elasticsearch deployment include:
 
-You can configure your Elasticsearch deployment to:
-
-* configure storage for your Elasticsearch cluster;  
-* define how shards are replicated across data nodes in the cluster, from full replication to no replication;
-* configure external access to Elasticsearch data. 
+* storage for your Elasticsearch cluster;  
+* how shards are replicated across data nodes in the cluster, from full replication to no replication;
+* allowing external access to Elasticsearch data. 
 
 [NOTE]
 ====
@@ -24,7 +21,7 @@ possibly resulting in shards not being allocated and replica shards being lost.
 
 //Following paragraph also in modules/cluster-logging-deploy-storage-considerations.adoc
 
-Elasticsearch is a memory-intensive application. Each Elasticsearch node needs 16G of memory for both memory requests and CPU limits, 
+Elasticsearch is a memory-intensive application. Each Elasticsearch node needs 16G of memory for both memory requests and limits, 
 unless you specify otherwise in the Cluster Logging Custom Resource. The initial set of {product-title} nodes might not be large enough 
 to support the Elasticsearch cluster. You must add additional nodes to the {product-title} cluster to run with the recommended
 or higher memory. 
diff --git a/logging/config/cluster-logging-log-forwarding.adoc b/logging/config/cluster-logging-log-forwarding.adoc
@@ -11,7 +11,7 @@ The cluster logging *Log Forwarding* feature enables administrators to configure
 :FeatureName: Log Forwarding
 include::modules/technology-preview.adoc[leveloffset=+1]
 
-Log Forwarding provides an easier way to forward logs to specific endpoints inside or outside your cluster than using the xref:../../logging/config/cluster-logging-external.adoc#cluster-logging-external[Fluentd plugins].
+Log Forwarding provides an easier way to forward logs to specific endpoints inside or outside your {product-title} cluster than using the xref:../../logging/config/cluster-logging-external.adoc#cluster-logging-external[Fluentd plugins].
 
 [NOTE]
 ====
diff --git a/logging/config/cluster-logging-management.adoc b/logging/config/cluster-logging-management.adoc
@@ -10,9 +10,9 @@ In order to modify certain components managed by the Cluster Logging Operator or
 
 In unmanaged state, the operators do not respond to changes in the CRs. The administrator assumes full control of individual component configurations and upgrades when in unmanaged state.
 
-In managed state, the Cluster Logging Operator (CLO) responds to changes in the Cluster Logging Custom Resource (CR) and attempts to update the cluster to match the CR.
+In managed state, the Cluster Logging Operator (CLO) responds to changes in the Cluster Logging Custom Resource (CR) and adjusts the logging deployment accordingly.
 
-The {product-title} documentation indicates in a prerequisite step when you must set the cluster to Unmanaged.
+The {product-title} documentation indicates in a prerequisite step when you must set the {product-title} cluster to Unmanaged.
 
 [NOTE]
 ====
diff --git a/modules/cluster-logging-about-components.adoc b/modules/cluster-logging-about-components.adoc
@@ -24,7 +24,7 @@ There are currently 5 different types of cluster logging components:
 * collection - This is the component that collects logs from the node, formats them, and stores them in the logStore. The current implementation is Fluentd.
 * visualization - This is the UI component used to view logs, graphs, charts, and so forth. The current implementation is Kibana.
 * curation - This is the component that trims logs by age. The current implementation is Curator.
-* event routing - This is the component forwards events to cluster logging. The current implementation is Event Router.
+* event routing - This is the component forwards {product-title} events to cluster logging. The current implementation is Event Router.
 
 ifndef::cnv-logging[]
 In this document, we may refer to logStore or Elasticsearch, visualization or Kibana, curation or Curator, collection or Fluentd, interchangeably, except where noted.
diff --git a/modules/cluster-logging-about-curator.adoc b/modules/cluster-logging-about-curator.adoc
@@ -5,7 +5,7 @@
 [id="cluster-logging-about-curator_{context}"]
 = About logging curation
 
-The Elasticsearch Curator tool performs scheduled maintenance operations on a global and/or on a per-project basis. Curator performs actions daily based on its configuration. Only one Curator Pod is
+The Elasticsearch Curator tool performs scheduled maintenance operations on a global and/or on a per-project basis. Curator performs actions based on its configuration. Only one Curator Pod is
 recommended per Elasticsearch cluster. 
 
 [source,yaml]
diff --git a/modules/cluster-logging-clo-status.adoc b/modules/cluster-logging-clo-status.adoc
@@ -137,7 +137,7 @@ A status message similar to the following indicates a node has exceeded the conf
     upgradeStatus: {}
 ----
 
-A status message similar to the following indicates a node has exceeded the configured high watermark and shard will be relocated to other nodes:
+A status message similar to the following indicates a node has exceeded the configured high watermark and shards will be relocated to other nodes:
 
 ----
   nodes:
diff --git a/modules/cluster-logging-collector-external.adoc b/modules/cluster-logging-collector-external.adoc
@@ -145,11 +145,11 @@ To configure the *out_forward* plug-in:
 +
 <1> Specify the default value of the auto-generated certificate common name (CN).
 <2> Enter the Shared key between nodes
-<3> Specify `true` to enable TLS validation.
-<4> Set to `true` to verify the server cert hostname. Set false to ignore server cert hostname.
+<3> Specify `tls` to enable TLS validation.
+<4> Set to `true` to verify the server cert hostname. Set to `false` to ignore server cert hostname.
 <5> Specify the path to private CA certificate file as `/etc/ocp-forward/ca_cert.pem`.
 +
-To use mTLS, see the link:https://docs.fluentd.org/output/forward#tips-and-tricks[Fluentd documentation] for information about client certificate and key parameters and other settings.
+To use mTLS, see the link:https://docs.fluentd.org/output/forward#tips-and-tricks[Fluentd documentation] for information about client certificate, key parameters, and other settings.
 
 .. Configure the name, host, and port for your external Fluentd server:
 +
@@ -158,19 +158,20 @@ To use mTLS, see the link:https://docs.fluentd.org/output/forward#tips-and-trick
   <server>
     name <1>
     host <2>
-    hostlabel <5>
-    port <3>
+    hostlabel <3>
+    port <4>
   </server>
-  <server> <4>
+  <server> <5>
     name
     host 
   </server>
 ----
 +
 <1> Optionally, enter a name for this receiver.
 <2> Specify the host name or IP of the receiver.
-<3> Specify the port of the receiver.
-<4> Optionally, add additional receivers. 
+<3> Specify the host label of the receiver.
+<4> Specify the port of the receiver.
+<5> Optionally, add additional receivers. 
 If you specify two or more receivers, `out_secure_forward` uses these server nodes in a round-robin order.
 +
 For example:
@@ -209,7 +210,7 @@ For example:
 $ oc create secret generic secure-forward --from-file=ca-bundle.crt=ca-for-fluentd-receiver/ca.crt --from-literal=shared_key=fluentd-receiver
 ----
 
-. Refresh the `fluentd` Pod to apply the `secure-forward` secret and `secure-forward` ConfigMap:
+. Refresh the `fluentd` Pods to apply the `secure-forward` secret and `secure-forward` ConfigMap:
 +
 ----
 $ oc delete pod --selector logging-infra=fluentd
@@ -219,6 +220,6 @@ $ oc delete pod --selector logging-infra=fluentd
 +
 When configuring the recevier, it must be able to accept messages securely from {product-title}.
 
-You can find further explanation of link:https://docs.fluentd.org/v1.0/articles/in_forward[how to set up the *inforward* plug-in] and link:https://docs.fluentd.org/v1.0/articles/out_forward[the *out_forward* plug-in].
+You can find further explanation of link:https://docs.fluentd.org/v1.0/articles/in_forward[how to set up the *in_forward* plug-in] and link:https://docs.fluentd.org/v1.0/articles/out_forward[the *out_forward* plug-in].
 
 
diff --git a/modules/cluster-logging-collector-json.adoc b/modules/cluster-logging-collector-json.adoc
@@ -16,7 +16,7 @@ Enabling this feature comes with risks, including:
 
 * Possible log loss due to Elasticsearch rejecting documents due to inconsistent type mappings.
 * Potential buffer storage leak caused by rejected message cycling.
-* Overwrite of data for field with same names.
+* Overwriting data for fields with the same name.
 
 The features in this topic should be used by only experienced Fluentd and Elasticsearch users.
 ====
diff --git a/modules/cluster-logging-collector-tolerations.adoc b/modules/cluster-logging-collector-tolerations.adoc
@@ -9,18 +9,17 @@ You can ensure which nodes the logging collector Pods run on and prevent
 other workloads from using those nodes by using tolerations on the Pods.
 
 You apply tolerations to logging collector Pods through the Cluster Logging Custom Resource (CR)
-and apply taints to a node through the node specification. A taint on a node is a `key:value pair` that 
-instructs the node to repel all Pods that do not tolerate the taint. Using a specific `key:value` pair
-that is not on other Pods ensures only logging collector Pods can run on that node.
+and apply taints to a node through the node specification. You can use taints and tolerations
+to ensure the Pod does not get evicted for things like memory and CPU issues.
 
 By default, the logging collector Pods have the following toleration:
 
 [source, yaml]
 ----
 tolerations:
-- effect: "NoExecute"
-  key: "node-role.kubernetes.io/master"
+- key: "node-role.kubernetes.io/master"
   operator: "Exists"
+  effect: "NoExecute"
 ----
 
 .Prerequisites
@@ -42,7 +41,7 @@ $ oc adm taint nodes node1 collector=node:NoExecute
 ----
 +
 This example places a taint on `node1` that has key `collector`, value `node`, and taint effect `NoExecute`.
-You must use the `NoExecute` effect schedule. `NoExecute` schedules only Pods that match the taint and remove existing Pods
+You must use the `NoExecute` taint effect. `NoExecute` schedules only Pods that match the taint and removes existing Pods
 that do not match.
 
 . Edit the `collection` section of the Cluster Logging Custom Resource (CR) to configure a toleration for the logging collector Pods:
@@ -64,5 +63,5 @@ that do not match.
 <3> Specify the `NoExecute` effect.
 <4> Optionally, specify the `tolerationSeconds` parameter to set how long a Pod can remain bound to a node before being evicted.
 
-This toleration matches the taint created by the `oc adm taint` command. A Pod this toleration would be able to schedule onto `node1`.
+This toleration matches the taint created by the `oc adm taint` command. A Pod with this toleration would be able to schedule onto `node1`.
 
diff --git a/modules/cluster-logging-collector-undefined.adoc b/modules/cluster-logging-collector-undefined.adoc
@@ -58,7 +58,7 @@ The `CDM_DEFAULT_KEEP_FIELDS` parameter is for only advanced users, or if you ar
 
 * Empty fields. You can determine which empty fields to retain from disparate logs.
 
-.Environment parameters for log normalization
+.Environment variables for log normalization
 [cols="2,4a,2", options="header"]
 |===
 |Parameters  |Definition  |Example
diff --git a/modules/cluster-logging-curator-tolerations.adoc b/modules/cluster-logging-curator-tolerations.adoc
@@ -32,7 +32,7 @@ $ oc adm taint nodes node1 curator=node:NoExecute
 ----
 +
 This example places a taint on `node1` that has key `curator`, value `node`, and taint effect `NoExecute`.
-You must use the `NoExecute` effect schedule. `NoExecute` schedules only Pods that match the taint and remove existing Pods
+You must use the `NoExecute` taint effect. `NoExecute` schedules only Pods that match the taint and remove existing Pods
 that do not match.
 
 . Edit the `curation` section of the Cluster Logging Custom Resource (CR) to configure a toleration for the Curator Pod:
@@ -53,5 +53,5 @@ that do not match.
 <3> Specify the `NoExecute` effect.
 <4> Optionally, specify the `tolerationSeconds` parameter to set how long a Pod can remain bound to a node before being evicted.
 
-This toleration matches the taint that is created by the `oc adm taint` command. A Pod this toleration would be able to schedule onto `node1`.
+This toleration matches the taint that is created by the `oc adm taint` command. A Pod with this toleration would be able to schedule onto `node1`.
 
diff --git a/modules/cluster-logging-deploy-clo-cli.adoc b/modules/cluster-logging-deploy-clo-cli.adoc
@@ -201,7 +201,7 @@ spec:
       fluentd: {}
 ----
 <1> The name must be `instance`.
-<2> The Cluster Logging management state. In most cases, if you change the default Cluster Logging defaults, you must set this to `Unmanaged`.
+<2> The Cluster Logging management state. In most cases, if you change the Cluster Logging defaults, you must set this to `Unmanaged`.
 However, an unmanaged deployment does not receive updates until Cluster Logging is placed back into the `Managed` state. For more information, see *Changing cluster logging management state*.
 <3> Settings for configuring Elasticsearch. Using the Custom Resource (CR), you can configure shard replication policy and persistent storage. For more information, see *Configuring Elasticsearch*.
 <4> Specify the number of Elasticsearch nodes. See the note that follows this list.
diff --git a/modules/cluster-logging-deploy-clo.adoc b/modules/cluster-logging-deploy-clo.adoc
@@ -171,7 +171,7 @@ spec:
       fluentd: {}
 ----
 <1> The name must be `instance`.
-<2> The cluster logging management state. In most cases, if you change the default cluster logging defaults, you must set this to `Unmanaged`.
+<2> The cluster logging management state. In most cases, if you change the cluster logging defaults, you must set this to `Unmanaged`.
 However, an unmanaged deployment does not receive updates until the cluster logging is placed back into a managed state. For more information, see *Changing cluster logging management state*.
 <3> Settings for configuring Elasticsearch. Using the CR, you can configure shard replication policy and persistent storage. For more information, see *Configuring Elasticsearch*.
 <4> Specify the number of Elasticsearch nodes. See the note that follows this list.
diff --git a/modules/cluster-logging-deploy-storage-considerations.adoc b/modules/cluster-logging-deploy-storage-considerations.adoc
@@ -13,7 +13,7 @@ be used to increase overall disk performance.
 
 //Following paragraph also in nodes/cluster-logging-elasticsearch
 
-Elasticsearch is a memory-intensive application. The default cluster logging installation deploys 16G of memory for both memory requests and CPU limits.
+Elasticsearch is a memory-intensive application. The default cluster logging installation deploys 16G of memory for both memory requests and limits.
 The initial set of {product-title} nodes might not be large enough to support the Elasticsearch cluster. You must add additional nodes to the
 {product-title} cluster to run with the recommended or higher memory. Each Elasticsearch node can operate with a lower
 memory setting though this is not recommended for production deployments.
diff --git a/modules/cluster-logging-deploying-about.adoc b/modules/cluster-logging-deploying-about.adoc
@@ -133,7 +133,7 @@ You can select which log collector is deployed as a Daemonset to each node in th
 ////
 
 Curator schedule::
-You specify the schedule for Curator in the [cron format](https://en.wikipedia.org/wiki/Cron).
+You specify the schedule for Curator in the link:https://en.wikipedia.org/wiki/Cron[cron format].
 
 ----
   spec:
diff --git a/modules/cluster-logging-elasticsearch-rules.adoc b/modules/cluster-logging-elasticsearch-rules.adoc
@@ -28,7 +28,7 @@ You can view these alerting rules in Prometheus.
 
 |ElasticsearchNodeDiskWatermarkReached
 |Disk Low Watermark Reached at node in cluster. Shards can not be allocated to this node anymore. You should
-consider adding more disk to the node.
+consider adding more disk space to the node.
 |alert
 
 |ElasticsearchNodeDiskWatermarkReached
diff --git a/modules/cluster-logging-elasticsearch-status-viewing.adoc b/modules/cluster-logging-elasticsearch-status-viewing.adoc
@@ -131,7 +131,7 @@ status:
     upgradeStatus: {}
 ----
 
-This status message indicates a node has exceeded the configured high watermark and shard will be relocated to other nodes.
+This status message indicates a node has exceeded the configured high watermark and shards will be relocated to other nodes.
 
 ----
 status:
diff --git a/modules/cluster-logging-elasticsearch-storage.adoc b/modules/cluster-logging-elasticsearch-storage.adoc
@@ -5,7 +5,7 @@
 [id="cluster-logging-elasticsearch-storage_{context}"]
 = Configuring Elasticsearch storage
 
-Elasticsearch requires persistent storage.  The faster the storage, the faster the Elasticsearch performance is.
+Elasticsearch requires persistent storage.  The faster the storage, the faster the Elasticsearch performance.
 
 .Prerequisites
  
diff --git a/modules/cluster-logging-elasticsearch-tolerations.adoc b/modules/cluster-logging-elasticsearch-tolerations.adoc
diff --git a/modules/cluster-logging-kibana-tolerations.adoc b/modules/cluster-logging-kibana-tolerations.adoc
diff --git a/modules/cluster-logging-log-forwarding-about.adoc b/modules/cluster-logging-log-forwarding-about.adoc
diff --git a/modules/cluster-logging-log-forwarding-configure.adoc b/modules/cluster-logging-log-forwarding-configure.adoc
diff --git a/modules/cluster-logging-systemd-scaling.adoc b/modules/cluster-logging-systemd-scaling.adoc
diff --git a/modules/cluster-logging-upgrading-logging.adoc b/modules/cluster-logging-upgrading-logging.adoc
