RHDEVDOCS-4426-mod w/ peer review

logging/.meta-logging-quickref.adoc

@@ -31,6 +31,7 @@ Files referenced only apply to versions 5.5+ of logging.
 ** logging-rn-5.5.2.adoc
 ** logging-rn-5.5.1.adoc
 ** logging-rn-5.5.0.adoc
+** logging-loki-retention.adoc
 
 
 * Snippets
@@ -42,3 +43,4 @@ Files referenced only apply to versions 5.5+ of logging.
 ** logging-supported-config-snip.adoc[]
 ** logging-approval-strategy-snip.adoc[]
 ** logging-subscription-object-snip.adoc[
+** logging-create-apply-cr-snip.adoc[]

logging/cluster-logging-loki.adoc

@@ -10,6 +10,8 @@ include::modules/cluster-logging-loki-about.adoc[leveloffset=+1]
 
 include::modules/cluster-logging-loki-deploy.adoc[leveloffset=+1]
 
+include::modules/logging-loki-retention.adoc[leveloffset=+1]
+
 include::modules/cluster-logging-forwarding-lokistack.adoc[leveloffset=+1]
 
 include::modules/cluster-logging-troubleshooting-loki-entry-out-of-order-errors.adoc[leveloffset=+2]

modules/logging-loki-retention.adoc

@@ -0,0 +1,102 @@
+// Module included in the following assemblies:
+//
+:_content-type: PROCEDURE
+[id="logging-loki-retention_{context}"]
+= Enabling stream-based retention with Loki
+With Logging version 5.6 and higher, you can configure retention policies based on log streams. Rules for these may be set globally, per tenant, or both. If you configure both, tenant rules apply before global rules.
+
+. To enable stream-based retention,  create or edit the `LokiStack` custom resource (CR):
+
+include::snippets/logging-create-apply-cr-snip.adoc[lines=9..12]
+
+. You can refer to the examples below to configure your LokiStack CR.
+
+.Example global stream-based retention
+[source,yaml]
+----
+apiVersion: loki.grafana.com/v1
+kind: LokiStack
+metadata:
+  name: lokistack-sample
+  namespace: openshift-logging
+spec:
+  limits:
+    global: <1>
+      retention: <2>
+        days: 20
+        streams:
+        - days: 4
+          priority: 1
+          selector: '{kubernetes_namespace_name=~"test.+"}' <3>
+        - days: 1
+          priority: 1
+          selector: '{log_type="infrastructure"}'
+  managementState: Managed
+  replicationFactor: 1
+  size: 1x.small
+  storage:
+    schemas:
+    - effectiveDate: "2020-10-11"
+      version: v11
+    secret:
+      name: gcs-secret
+      type: gcstest
+  storageClassName: standard
+  tenants:
+    mode: openshift-logging
+----
+<1> Sets retention policy for all log streams. *Note: This field does not impact the retention period for stored logs in object storage.*
+<2> Retention is enabled in the cluster when this block is added to the CR.
+<3> Contains the link:https://grafana.com/docs/loki/latest/logql/query_examples/#query-examples[LogQL query] used to define the log stream.
+
+.Example per-tenant stream-based retention
+[source,yaml]
+----
+apiVersion: loki.grafana.com/v1
+kind: LokiStack
+metadata:
+  name: lokistack-sample
+  namespace: openshift-logging
+spec:
+  limits:
+    global:
+      retention:
+        days: 20
+    tenants: <1>
+      application:
+        retention:
+          days: 1
+          streams:
+            - days: 4
+              selector: '{kubernetes_namespace_name=~"test.+"}' <2>
+      infrastructure:
+        retention:
+          days: 5
+          streams:
+            - days: 1
+              selector: '{kubernetes_namespace_name=~"openshift-cluster.+"}'
+  managementState: Managed
+  replicationFactor: 1
+  size: 1x.small
+  storage:
+    schemas:
+    - effectiveDate: "2020-10-11"
+      version: v11
+    secret:
+      name: gcs-secret
+      type: gcs
+  storageClassName: standard
+  tenants:
+    mode: openshift-logging
+----
+<1> Sets retention policy by tenant. Valid tenant types are `application`, `audit`, and `infrastructure`.
+<2> Contains the link:https://grafana.com/docs/loki/latest/logql/query_examples/#query-examples[LogQL query] used to define the log stream.
+
+. Then apply your configuration:
+
+include::snippets/logging-create-apply-cr-snip.adoc[lines=14..17]
+
+[NOTE]
+====
+This is not for managing the retention for stored logs. Global retention periods for stored logs to a supported maximum of 30 days is configured with your object storage.
+====

snippets/logging-create-apply-cr-snip.adoc

@@ -0,0 +1,17 @@
+// Text snippet included in the following assemblies:
+//
+//
+// Text snippet included in the following modules:
+//
+//
+:_content-type: SNIPPET
+
+[source,yaml]
+----
+oc create -f <file-name>.yaml
+----
+
+[source,yaml]
+----
+oc apply -f <file-name>.yaml
+----