OBSDOCS-822: Log Collector Output Tuning

modules/logging-collector-output-tuning.adoc

@@ -0,0 +1,51 @@
+// Module included in the following assemblies:
+//
+// * list assemblies
+
+:_mod-docs-content-type: REFERENCE
+[id="logging-collector-output-tuning_{context}"]
+= Tuning log collector outputs
+
+In {logging} 5.9 and newer versions, the _performance tuning API_ provides a means of configuring your deployment to prioritize either throughput or durability of logs.
+
+For example, if you need to reduce the possibility of log loss when the collector restarts, or you require collected log messages to survive a collector restart to support regulatory mandates, you can tune your deployment to prioritize log durability.
+
+If you use outputs that have hard limitations on the size of batches they can receive, you may want to tune your deployment to prioritize log throughput.
+
+[IMPORTANT]
+====
+To use this feature, your {logging} deployment must be configured to use the Vector collector. The `tuning` spec in the `ClusterLogForwarder` custom resource (CR) is not supported when using the Fluentd collector.
+====
+
+The following example shows the `ClusterLogForwarder` CR options that you can modify to tune log forwarder outputs:
+
+[source,yaml]
+----
+apiVersion: logging.openshift.io/v1
+kind: ClusterLogForwarder
+metadata:
+# ...
+spec:
+  tuning:
+    properties:
+      delivery: AtLeastOnce # <1>
+      compression: none # <2>
+      maxWrite: <integer> # <3>
+      minRetryDuration: 1s # <4>
+      maxRetryDuration: 1s # <5>
+      reconnect: # <6>
+        maxDelay: 1s # <7>
+      batch:
+        maxBytes: 50K # <8>
+# ...
+----
+<1> Specify the delivery mode for log forwarding. The default delivery mode value is `AtLeastOnce`. This means that if the log forwarder crashes or is restarted, any logs that were read before the crash but not sent to their destination are re-read and re-sent. Log delivery is guaranteed, however it is possible that some logs are duplicated in the event of a crash, since log records are delivered "at least once".
++
+Alternatively, you can configure the `AtMostOnce` delivery mode. This means that the log forwarder makes no effort to recover logs lost during a crash. This mode gives better throughput, but may result in greater log loss.
+<2> Specifying a `compression` configuration causes data to be compressed before it is sent over the network. If the specified compression type is not supported by the output, this results in an error. The possible values for this configuration are `''` or `none` for no compression, `gzip`, `snappy`, `zlib`, or `zstd`.
+<3> Specifies a limit for the maximum payload in bytes of a single send operation to the output.
+<4> Specifies a minimum time to wait in seconds between attempts before retrying delivery after a failure.
+<5> Specifies a maximum time to wait in seconds between attempts before retrying delivery after a failure.
+<6> Controls connect and reconnect attempts. Defaults are determined by the underlying sink.
+<7> Specifies a maximum time in seconds to wait before attempting to reconnect when connection is lost.
+<8> Specifies a maximum size for a batch of data for each write operation.