Merge pull request #48666 from libander/RHDEVDOCS-4029

RHDEVDOCS-4029 - Fowarding to separate indices

Author: bburt-rh

logging/cluster-logging-external.adoc

@@ -29,6 +29,8 @@ You cannot use the config map methods and the Cluster Log Forwarder in the same
 
 include::modules/cluster-logging-collector-log-forwarding-about.adoc[leveloffset=+1]
 
+include::modules/cluster-logging-forwarding-separate-indices.adoc[leveloffset=+1]
+
 include::modules/cluster-logging-collector-log-forwarding-supported-plugins-5-1.adoc[leveloffset=+1]
 
 include::modules/cluster-logging-collector-log-forwarding-supported-plugins-5-2.adoc[leveloffset=+1]
@@ -42,6 +44,7 @@ include::modules/cluster-logging-collector-log-forward-syslog.adoc[leveloffset=+
 include::modules/cluster-logging-collector-log-forward-cloudwatch.adoc[leveloffset=+1]
 
 include::modules/cluster-logging-collector-log-forward-loki.adoc[leveloffset=+1]
+
 include::modules/cluster-logging-troubleshooting-loki-entry-out-of-order-errors.adoc[leveloffset=+2]
 
 

modules/cluster-logging-forwarding-separate-indices.adoc

@@ -0,0 +1,68 @@
+// Module is included in the following assemblies:
+//cluster-logging-external
+:_content-type: PROCEDURE
+[id="cluster-logging-forwarding-separate-indices_{context}"]
+= Forwarding JSON logs from containers in the same pod to separate indices
+
+You can forward structured logs from different containers within the same pod to different indices. To use this feature, you must configure the pipeline with multi-container support and annotate the pods. Logs are written to indices with a prefix of `app-`. It is recommended that Elasticsearch be configured with aliases to accommodate this.
+
+[IMPORTANT]
+====
+JSON formatting of logs varies by application. Because creating too many indices impacts performance, limit your use of this feature to creating indices for logs that have incompatible JSON formats. Use queries to separate logs from different namespaces, or applications with compatible JSON formats.
+====
+
+.Prerequisites
+
+* {logging-title-uc}: 5.5
+
+.Procedure
+. Create or edit a YAML file that defines the `ClusterLogForwarder` CR object:
++
+[source,yaml]
+----
+apiVersion: "logging.openshift.io/v1"
+kind: ClusterLogForwarder
+metadata:
+  name: instance
+  namespace: openshift-logging
+spec:
+  outputDefaults:
+    elasticsearch:
+      enableStructuredContainerLogs: true <1>
+  pipelines:
+  - inputRefs:
+    - application
+    name: application-logs
+    outputRefs:
+    - default
+    parse: json
+----
+<1> Enables multi-container outputs.
+
+. Create or edit a YAML file that defines the `Pod` CR object:
++
+[source,yaml]
+----
+    apiVersion: v1
+    kind: Pod
+    metadata:
+      annotations:
+        containerType.logging.openshift.io/heavy: heavy <1>
+        containerType.logging.openshift.io/low: low
+    spec:
+      containers:
+      - name: heavy <2>
+        image: heavyimage
+      - name: low
+        image: lowimage
+----
+<1> Format: `containerType.logging.openshift.io/<container-name>: <index>`
+<2> Annotation names must match container names
+
+[WARNING]
+====
+This configuration might significantly increase the number of shards on the cluster.
+====
+
+.Additional Resources
+link:https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/[Kubernetes Annotations]