Discover

Red Hat OpenShift Logging 6.6

Introduction to OpenShift logging.

Red Hat OpenShift Documentation Team

Abstract

This document provides an overview of OpenShift Logging features, and also includes release notes and support information.

Chapter 1. Red Hat OpenShift Logging overview

The ClusterLogForwarder custom resource (CR) is the central configuration point for log collection and forwarding.

1.1. Inputs and outputs

Inputs specify the sources of logs to forward. Outputs define the destinations where logs are sent.

Logging provides the following built-in input types to select logs from different parts of your cluster:

  • application
  • receiver
  • infrastructure
  • audit

You can also define custom inputs based on namespaces or pod labels to fine-tune log selection.

Each output type has its own set of configuration options, allowing you to customize the behavior and authentication settings.

1.2. Receiver input type

The receiver input type enables the Logging system to accept logs from external sources. It supports two formats for receiving logs: http and syslog.

The ReceiverSpec field defines the configuration for a receiver input.

1.3. Pipelines and filters

Pipelines determine the flow of logs from inputs to outputs. A pipeline consists of one or more input refs, output refs, and optional filter refs. You can use filters to transform or drop log messages within a pipeline. The order of filters matters because they are applied sequentially, and earlier filters can prevent log messages from reaching later stages.

1.4. Operator behavior

The Cluster Logging Operator manages the deployment and configuration of the collector based on the managementState field of the ClusterLogForwarder resource:

  • When set to Managed (default), the Operator actively manages the logging resources to match the configuration defined in the spec.
  • When set to Unmanaged, the Operator does not take any action, allowing you to manually manage the logging components.

1.5. Validation

Logging includes extensive validation rules and default values to ensure a smooth and error-free configuration experience. The ClusterLogForwarder resource enforces validation checks on required fields, dependencies between fields, and the format of input values. Default values are provided for certain fields, which reduces the need for explicit configuration in common scenarios.

Chapter 2. Understanding an existing logging deployment

If you inherit a cluster with logging already configured, understand the current deployment before making changes. You can discover what logging components are installed, understand how logs are collected and forwarded, verify that the deployment is healthy, and audit storage and access control settings.

2.1. Discovering your logging deployment

When you inherit a cluster with logging already configured, start by identifying which logging components exist and their configuration. OpenShift Logging consists of up to three operators, each managing a different aspect of the logging stack.

The logging stack components are:

Red Hat OpenShift Logging Operator
Manages log collection and forwarding. When installed, it creates a ClusterLogForwarder custom resource that defines what logs to collect and where to send them.
Loki Operator
Manages the log store when using in-cluster storage. When installed, it creates a LokiStack custom resource that defines storage configuration, sizing, and retention policies.
Cluster Observability Operator (COO)
Manages visualization in the OpenShift Container Platform web console. When installed, it adds the Logs tab under Observe > Logs.

Understanding which operators exist tells you:

  • Whether the collector gathers logs (requires Red Hat OpenShift Logging Operator)
  • Whether LokiStack stores logs in-cluster or the collector forwards them externally
  • Whether you can view logs in the web console (requires COO)

After identifying installed operators, examine the custom resources they manage to understand the specific configuration:

  • ClusterLogForwarder - Defines log collection sources (inputs), destinations (outputs), and routing (pipelines)
  • LokiStack - Defines in-cluster log storage configuration, sizing, and retention
  • UIPlugin - Enables log visualization in the web console

2.2. Listing logging components

You can identify which logging operators exist and which custom resources they created by querying the cluster.

Procedure

  1. Check which logging operators exist: 

    $ oc get deployment -n openshift-logging cluster-logging-operator \
  -o jsonpath='{.metadata.name}{"\n"}' 2>/dev/null || echo "Cluster Logging Operator not found"
    $ oc get deployment -n openshift-operators-redhat loki-operator-controller-manager \
  -o jsonpath='{.metadata.name}{"\n"}' 2>/dev/null || echo "Loki Operator not found"
    $ oc get deployment -n openshift-cluster-observability-operator \
  cluster-observability-operator \
  -o jsonpath='{.metadata.name}{"\n"}' 2>/dev/null || echo "Cluster Observability Operator not found"

  2. List the ClusterLogForwarder resources: 

    $ oc get clusterlogforwarder -A

    Example output

    NAMESPACE          NAME       AGE
openshift-logging  instance   45d

    The ClusterLogForwarder named instance in the openshift-logging namespace is the default log forwarder.

  3. List the LokiStack resources: 

    $ oc get lokistack -A

    Example output

    NAMESPACE          NAME      AGE
openshift-logging  logging   45d

    If no LokiStack exists, the collector forwards logs to external destinations only.

  4. List the UIPlugin resources: 

    $ oc get uiplugin logging

    Example output

    logging   45d

    If no logging UIPlugin exists, the Logs tab is not available in the web console.

  5. Get the versions of the installed operators: 

    $ oc get csv -n openshift-logging -l operators.coreos.com/cluster-logging.openshift-logging \
  -o jsonpath='{.items[0].spec.version}{"\n"}'
    $ oc get csv -n openshift-operators-redhat -l operators.coreos.com/loki-operator.openshift-operators-redhat \
  -o jsonpath='{.items[0].spec.version}{"\n"}'
    $ oc get csv -n openshift-cluster-observability-operator -l operators.coreos.com/cluster-observability-operator.openshift-cluster-observability-operator \
  -o jsonpath='{.items[0].spec.version}{"\n"}'

2.3. Understanding log forwarding configuration

The ClusterLogForwarder custom resource defines which logs to collect, where to send them, and how to process them. You can examine the configuration to understand the current log flow.

Procedure

  1. View the complete ClusterLogForwarder configuration: 

    $ oc get clusterlogforwarder instance -n openshift-logging -o yaml

  2. Identify which logs the collector gathers by examining the spec.pipelines section: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{range .spec.pipelines[*]}{.inputRefs[*]}{"\n"}{end}' | sort -u

    Example output

    application
audit
infrastructure

    The default log input types are:

    • application - Logs from application containers
    • infrastructure - Logs from OpenShift and Kubernetes infrastructure components

    • audit - Audit logs from the Kubernetes API server, node audit, and OpenShift OAuth

      These inputs exist by default and do not need to be defined in spec.inputs. Custom inputs in spec.inputs are used to filter logs or define receivers for non-cluster sources.

  3. Identify where the collector sends logs by examining the spec.outputs section: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{range .spec.outputs[*]}{.name}{"\t"}{.type}{"\n"}{end}'

    Example output

    default-lokistack	lokiStack
splunk-prod	        splunk

    This output shows logs are sent to both a LokiStack and an external Splunk instance.

  4. Understand how the pipelines route logs by examining the spec.pipelines section: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{range .spec.pipelines[*]}{.name}{"\n  inputs: "}{.inputRefs}{"\n  outputs: "}{.outputRefs}{"\n"}{end}'

    Example output

    application-logs
  inputs: [application]
  outputs: [default-lokistack]
infrastructure-logs
  inputs: [infrastructure]
  outputs: [default-lokistack]
audit-logs
  inputs: [audit]
  outputs: [default-lokistack splunk-prod]

    This output shows that:

    • Application logs go to the LokiStack
    • Infrastructure logs go to the LokiStack
    • Audit logs go to both the LokiStack and Splunk

  5. Check if any filters are applied: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{.spec.filters}'

    If the output is empty or null, no filters are configured. Filters can drop or modify log records before forwarding.

  6. Check if any receivers are configured to accept logs from non-cluster sources: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{.spec.inputs[?(@.receiver)].name}'

    If output appears, the ClusterLogForwarder includes receivers that accept logs from external sources via HTTP or other protocols. View the receiver configuration with: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{.spec.inputs[?(@.receiver)]}' | python3 -m json.tool

  7. Identify which service account has collector permissions: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{.spec.serviceAccount.name}'

    Example output

    logcollector

    This service account must have the appropriate ClusterRoleBindings for the log types being collected.

2.4. Checking logging deployment health

After understanding the logging configuration, verify that all components are running and logs are flowing correctly.

Procedure

  1. Check the ClusterLogForwarder status conditions: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{.status.conditions}' | python3 -m json.tool

    Example healthy output

    [
    {
        "lastTransitionTime": "2026-06-01T14:52:07Z",
        "message": "permitted to collect log types: [application audit infrastructure]",
        "reason": "ClusterRolesExist",
        "status": "True",
        "type": "observability.openshift.io/Authorized"
    },
    {
        "lastTransitionTime": "2026-06-01T14:52:07Z",
        "message": "",
        "reason": "ValidationSuccess",
        "status": "True",
        "type": "observability.openshift.io/Valid"
    },
    {
        "lastTransitionTime": "2026-06-01T14:52:07Z",
        "message": "",
        "reason": "ReconciliationComplete",
        "status": "True",
        "type": "Ready"
    }
]

    All three conditions should show "status": "True":

    • Authorized confirms the collector service account has required permissions
    • Valid confirms the ClusterLogForwarder configuration is correct

    • Ready confirms the Operator successfully reconciled the configuration

      If any condition shows "status": "False", check the message field for details.

  2. Verify that collector pods are running: 

    $ oc get pods -n openshift-logging -l app.kubernetes.io/component=collector

    Example output

    NAME               READY   STATUS    RESTARTS   AGE
instance-abc123    1/1     Running   0          45d
instance-def456    1/1     Running   0          45d
instance-ghi789    1/1     Running   0          45d

    You should see one collector pod per cluster node. All pods should show Running status and 1/1 ready.

  3. If a LokiStack exists, check its status: 

    $ oc get lokistack logging-loki -n openshift-logging \
  -o jsonpath='{.status.conditions}' | python3 -m json.tool
    Note

    This example uses logging-loki as the LokiStack name, which is the default name shown in the installation documentation. If you used a different name when creating your LokiStack, replace logging-loki with your actual LokiStack name. You can list all LokiStack instances by running: 

    $ oc get lokistack -n openshift-logging

    Look for the Ready condition with "status": "True".

  4. Verify that logs are flowing by checking recent log entries in the web console:

    1. In the OpenShift Container Platform web console, go to Observe > Logs.
    2. Select a log type such as infrastructure.

    3. Verify that recent log entries appear with timestamps from the last few minutes.

      If no logs appear, check the collector pod logs for errors: 

      $ oc logs -n openshift-logging -l app.kubernetes.io/component=collector --tail=50

  5. Check for common error messages in collector logs: 

    $ oc logs -n openshift-logging -l app.kubernetes.io/component=collector --tail=200 \
  | grep -i "error\|failed\|certificate\|connection"

    Common issues:

    • Certificate errors indicate missing or incorrect TLS configuration
    • Connection errors indicate network issues reaching output destinations
    • Authorization errors indicate missing ClusterRoleBindings

2.5. Auditing log storage and retention

Understanding storage configuration helps you assess costs, plan capacity, and ensure that retention policies meet compliance requirements.

Procedure

  1. Check if LokiStack stores logs in-cluster: 

    $ oc get lokistack -A

    If a LokiStack exists, it is configured to store logs in-cluster. If not, the collector forwards all logs to external destinations.

  2. View the LokiStack size tier: 

    $ oc get lokistack logging-loki -n openshift-logging \
  -o jsonpath='{.spec.size}'
    Note

    This example uses logging-loki as the LokiStack name. If you used a different name, replace logging-loki with your actual LokiStack name.

    Example output

    1x.small

    The size tier determines the resource allocation and ingestion rate capacity.

  3. Check the object storage configuration: 

    $ oc get lokistack logging-loki -n openshift-logging \
  -o jsonpath='{.spec.storage}' | python3 -m json.tool

    Example output

    {
    "schemas": [
        {
            "effectiveDate": "2023-12-16",
            "version": "v13"
        }
    ],
    "secret": {
        "name": "logging-loki-s3",
        "type": "s3"
    }
}

    This shows the secret that contains the S3-compatible object storage configuration. The LokiStack requires both PVC storage (for indexes) and object storage (for log data).

  4. View retention policies: 

    $ oc get lokistack logging-loki -n openshift-logging \
  -o jsonpath='{.spec.limits.global.retention}' | python3 -m json.tool

    Example output

    {
    "days": 7,
    "streams": [
        {
            "days": 30,
            "priority": 1,
            "selector": "{log_type=\"audit\"}"
        }
    ]
}

    This output shows:

    • Global retention: 7 days for all logs
    • Audit logs: 30 days retention (overrides global)

  5. Check PVC storage consumption: 

    $ oc get pvc -n openshift-logging -l app.kubernetes.io/name=lokistack

    Example output

    NAME                                     STATUS   VOLUME                CAPACITY   ACCESS MODES
storage-logging-compactor-0              Bound    pvc-abc123            10Gi       RWO
storage-logging-index-gateway-0          Bound    pvc-def456            10Gi       RWO
storage-logging-ingester-0               Bound    pvc-ghi789            10Gi       RWO
storage-logging-querier-0                Bound    pvc-jkl012            10Gi       RWO

    This shows the persistent volume claims for LokiStack components. The CAPACITY column shows allocated storage.

  6. View PVC usage percentage using a PromQL query in the web console (Observe > Metrics): 

    (
  kubelet_volume_stats_used_bytes{namespace="openshift-logging", persistentvolumeclaim=~"storage-logging.*"}
  /
  kubelet_volume_stats_capacity_bytes{namespace="openshift-logging", persistentvolumeclaim=~"storage-logging.*"}
) * 100

    This shows the percentage of used storage for each LokiStack PVC.

  7. If the collector forwards logs to external destinations, list the output configurations: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{range .spec.outputs[*]}{.name}{"\t"}{.type}{"\t"}{.url}{"\n"}{end}'

    This shows where the collector sends logs externally. Those systems manage retention for external destinations, not OpenShift Logging.

2.6. Understanding log access control

Log access control determines who can view logs in the web console and through the LokiStack API. Understanding the current access control configuration helps you assess security posture and plan changes.

Procedure

  1. Check if tenant mode is enabled: 

    $ oc get lokistack logging-loki -n openshift-logging \
  -o jsonpath='{.spec.tenants.mode}'
    Note

    This example uses logging-loki as the LokiStack name. If you used a different name, replace logging-loki with your actual LokiStack name.

    Example output

    openshift-logging

    • openshift-logging (or dynamic): Fine-grained access control is enabled. Users can query logs based on their namespace access.
    • If the command returns empty or the LokiStack does not exist, external systems manage access control.

  2. View the collector service account: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{.spec.serviceAccount.name}'

    This service account must have ClusterRoleBindings for the log types it collects.

  3. Check which log types the collector is authorized to collect: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{.status.conditions[?(@.type=="observability.openshift.io/Authorized")].message}'

    Example output

    permitted to collect log types: [application audit infrastructure]

  4. List the ClusterRoleBindings for the collector service account:

    First, get the service account name from the ClusterLogForwarder: 

    $ SA_NAME=$(oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{.spec.serviceAccount.name}')

    Then list the ClusterRoleBindings for that service account: 

    $ oc get clusterrolebinding -o json | \
  jq -r ".items[] | select(.subjects[]?.name==\"$SA_NAME\") | .metadata.name"

    Example output

    logcollector-application
logcollector-audit
logcollector-infrastructure

    Each ClusterRoleBinding grants permission to collect a specific log type.

  5. Check namespace-level access to logs (when tenant mode is enabled): 

    $ oc get rolebinding -n _<namespace>_ -o json | \
  jq -r '.items[] | select(.roleRef.name=="cluster-logging-application-view") | {name: .metadata.name, subjects: .subjects}'

    Replace <namespace> with a specific namespace to check. This shows which users or service accounts can view application logs from that namespace.

  6. List users with cluster-wide log access: 

    $ oc get clusterrolebinding -o json | \
  jq -r '.items[] | select(.roleRef.name=="cluster-logging-application-view") | {name: .metadata.name, subjects: .subjects}'

    This shows cluster-level bindings that grant log access across all namespaces.

  7. If using an external log destination, check the output authentication configuration: 

    $ oc get clusterlogforwarder instance -n openshift-logging \
  -o jsonpath='{range .spec.outputs[*]}{.name}{"\t"}{.type}{"\t"}{.authentication}{"\n"}{end}'

    This shows how the collector authenticates to external destinations. Secrets store sensitive credentials.

2.7. Additional resources

Chapter 3. Cluster logging support

Ensure cluster stability and full support by using only official logging configurations.

Configuration paradigms might change across OpenShift Container Platform releases, and such cases can only be handled gracefully if all configuration possibilities are controlled. If you use configurations other than those described in this documentation, your changes will be overwritten, because Operators are designed to reconcile any differences.

Note

If you must perform configurations not described in the OpenShift Container Platform documentation, you must set your Red Hat OpenShift Logging Operator to Unmanaged. An unmanaged logging instance is not supported and does not receive updates until you return its status to Managed.

Note

Logging is provided as an installable component, with a distinct release cycle from the core OpenShift Container Platform. The Red Hat Red Hat OpenShift Logging Life Cycle Policy outlines release compatibility.

Loki is a horizontally scalable, highly available, multitenant log aggregation system offered as a GA log store for logging for Red Hat OpenShift that can be visualized with the OpenShift Observability UI. The Loki configuration provided by OpenShift Logging is a short-term log store designed to help users perform fast troubleshooting with the collected logs. For that purpose, the logging for Red Hat OpenShift configuration of Loki has short-term storage, and is optimized for very recent queries. For long-term storage or queries over a long time period, users should look to log stores external to their cluster.

Elasticsearch indexes incoming log records completely during ingestion. Loki indexes only a few fixed labels during ingestion and defers more complex parsing until after the logs have been stored. This means Loki can collect logs more quickly.

3.1. Logging capabilities and limitations

Logging for Red Hat OpenShift is an opinionated collector and normalizer of application, infrastructure, and audit logs. It is intended to be used for forwarding logs to various supported systems.

Logging is not:

  • Security Information and Event Monitoring (SIEM) compliant
  • A "bring your own" (BYO) log collector configuration
  • Historical or long term log retention or storage
  • A guaranteed log sink
  • Secure storage - audit logs are not stored by default

3.2. Supported API custom resource definitions

The following table describes the supported Logging APIs.

Table 3.1. Logging API support states

CustomResourceDefinition (CRD)ApiVersionSupport state

LokiStack

lokistack.loki.grafana.com/v1

Supported from 5.5

RulerConfig

rulerconfig.loki.grafana/v1

Supported from 5.7

AlertingRule

alertingrule.loki.grafana/v1

Supported from 5.7

RecordingRule

recordingrule.loki.grafana/v1

Supported from 5.7

LogFileMetricExporter

LogFileMetricExporter.logging.openshift.io/v1alpha1

Supported from 5.8

ClusterLogForwarder

clusterlogforwarder.observability.openshift.io/v1

Supported from 6.0

3.3. Unsupported configurations

You must set the Red Hat OpenShift Logging Operator to the Unmanaged state to modify the following components:

  • The collector configuration file
  • The collector daemonset

Explicitly unsupported cases include:

  • Configuring the logging collector using environment variables. You cannot use environment variables to modify the log collector.
  • Configuring how the log collector normalizes logs. You cannot modify default log normalization.

3.4. Support policy for unmanaged Operators

The management state of an Operator determines whether an Operator is actively managing the resources for its related component in the cluster as designed. If an Operator is set to an unmanaged state, it does not respond to changes in configuration nor does it receive updates.

Although useful for non-production or debugging, Operators in an unmanaged state are unsupported, and the cluster administrator assumes full responsibility for configuration and upgrades.

An Operator can be set to an unmanaged state by using the following methods:

  • Individual Operator configuration

    Individual Operators have a managementState parameter in their configuration. This can be accessed in different ways, depending on the Operator. For example, the Red Hat OpenShift Logging Operator accomplishes this by modifying a custom resource (CR) that it manages, while the Cluster Samples Operator uses a cluster-wide configuration resource.

    Changing the managementState parameter to Unmanaged means that the Operator is not actively managing its resources and will take no action related to the related component. Some Operators might not support this management state as it might damage the cluster and require manual recovery.

    Warning

    Changing individual Operators to the Unmanaged state renders that particular component and functionality unsupported. Reported issues must be reproduced in Managed state for support to proceed.

  • Cluster Version Operator (CVO) overrides

    The spec.overrides parameter can be added to the CVO’s configuration to allow administrators to provide a list of overrides to the CVO’s behavior for a component. Setting the spec.overrides[].unmanaged parameter to true for a component blocks cluster upgrades and alerts the administrator after a CVO override has been set:

    Example output

    Disabling ownership via cluster version overrides prevents upgrades. Please remove overrides before continuing.

    Warning

    Setting a CVO override puts the entire cluster in an unsupported state. Reported issues must be reproduced after removing any overrides for support to proceed.

3.5. Collecting logging data for Red Hat Support

When opening a support case, provide debugging information about your cluster to Red Hat Support.

You can use the must-gather tool to collect diagnostic information for project-level resources, cluster-level resources, and each of the logging components. For prompt support, supply diagnostic information for both OpenShift Container Platform and logging.

3.5.1. About the must-gather tool

The oc adm must-gather CLI command collects the information from your cluster that is most likely needed for debugging issues.

For your logging, must-gather collects the following information:

  • Project-level resources, including pods, config maps, service accounts, roles, role bindings, and events at the project level
  • Cluster-level resources, including nodes, roles, and role bindings at the cluster level
  • OpenShift Logging resources in the openshift-logging and openshift-operators-redhat namespaces, including health status for the log collector, the log store, and the log visualizer

When you run oc adm must-gather, a new pod is created on the cluster. The data is collected on that pod and saved in a new directory that starts with must-gather.local. This directory is created in the current working directory.

3.5.2. Collecting logging data

You can use the oc adm must-gather CLI command to collect information about logging.

Procedure

  1. Navigate to the directory where you want to store the must-gather information.

  2. Run the oc adm must-gather command against the logging image: 

    $ oc adm must-gather --image=$(oc -n openshift-logging get deployment.apps/cluster-logging-operator -o jsonpath='{.spec.template.spec.containers[?(@.name == "cluster-logging-operator")].image}')

    The must-gather tool creates a new directory that starts with must-gather.local within the current directory. For example: must-gather.local.4157245944708210408.

  3. Create a compressed file from the must-gather directory that was just created. For example, on a computer that uses a Linux operating system, run the following command: 

    $ tar -cvaf must-gather.tar.gz must-gather.local.4157245944708210408
  4. Attach the compressed file to your support case on the Red Hat Customer Portal.

3.6. Additional resources

Chapter 4. Visualization for logging

Enhance the observability capabilities of the Red Hat OpenShift Logging web console by installing and managing UI plugins.

4.1. Additional resources

Legal Notice

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.