Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

About OpenShift logging

Red Hat OpenShift Logging 6.3

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
Copy link

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

1.1. Inputs and outputs
Copy link

Inputs specify the sources of logs to be forwarded. Logging provides the following built-in input types that 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.

Outputs define the destinations where logs are sent. Each output type has its own set of configuration options, allowing you to customize the behavior and authentication settings.

1.2. Receiver input type
Copy link

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
Copy link

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, as they are applied sequentially, and earlier filters can prevent log messages from reaching later stages.

1.4. Operator behavior
Copy link

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
Copy link

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, reducing the need for explicit configuration in common scenarios.

Chapter 2. Cluster logging support
Copy link

Only the configuration options described in this documentation are supported for logging.

Do not use any other configuration options, as they are unsupported. 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 OpenShift Container Platform Life Cycle Policy outlines release compatibility.

Loki is a horizontally scalable, highly available, multi-tenant 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 enable users to 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.

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:

  • A high scale log collection system
  • 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

2.1. Supported API custom resource definitions
Copy link

The following table describes the supported Logging APIs.

Expand
Table 2.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

2.2. Unsupported configurations
Copy link

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.

2.3. Support policy for unmanaged Operators
Copy link

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.

While this can be helpful in non-production clusters or during debugging, Operators in an unmanaged state are unsupported and the cluster administrator assumes full control of the individual component configurations and upgrades.

An Operator can be set to an unmanaged state 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: 

    Disabling ownership via cluster version overrides prevents upgrades. Please remove overrides before continuing.
    Copy to Clipboard Toggle word wrap
    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.

2.4. Collecting logging data for Red Hat Support
Copy link

When opening a support case, it is helpful to 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.

2.4.1. About the must-gather tool
Copy link

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, configuration 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.

2.4.2. Collecting logging data
Copy link

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

Procedure

To collect logging information with must-gather:

  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:

    If you are using OKD: 

    $ oc adm must-gather --image=quay.io/openshift/origin-cluster-logging-operator
    Copy to Clipboard Toggle word wrap

    Otherwise: 

    $ 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}')
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap
  4. Attach the compressed file to your support case on the Red Hat Customer Portal.

Chapter 3. Visualization for logging
Copy link

Visualization for logging is provided by deploying the Logging UI Plugin of the Cluster Observability Operator, which requires Operator installation.

Chapter 4. Quick start
Copy link

OpenShift Logging supports two data models:

  • ViaQ (General Availability)
  • OpenTelemetry (Technology Preview)

You can select either of these data models based on your requirement by configuring the lokiStack.dataModel field in the ClusterLogForwarder. ViaQ is the default data model when forwarding logs to LokiStack.

Note

In future releases of OpenShift Logging, the default data model will change from ViaQ to OpenTelemetry.

4.1. Quick start with ViaQ
Copy link

To use the default ViaQ data model, follow these steps:

Prerequisites

  • You have access to an OpenShift Container Platform cluster with cluster-admin permissions.
  • You installed the OpenShift CLI (oc).
  • You have access to a supported object store. For example, AWS S3, Google Cloud Storage, Azure, Swift, Minio, or OpenShift Data Foundation.

Procedure

  1. Install the Red Hat OpenShift Logging Operator, Loki Operator, and Cluster Observability Operator (COO) from OperatorHub.

  2. Create a LokiStack custom resource (CR) in the openshift-logging namespace: 

    apiVersion: loki.grafana.com/v1
kind: LokiStack
metadata:
  name: logging-loki
  namespace: openshift-logging
spec:
  managementState: Managed
  size: 1x.extra-small
  storage:
    schemas:
    - effectiveDate: '2024-10-01'
      version: v13
    secret:
      name: logging-loki-s3
      type: s3
  storageClassName: gp3-csi
  tenants:
    mode: openshift-logging
    Copy to Clipboard Toggle word wrap
    Note

    Ensure that the logging-loki-s3 secret is created beforehand. The contents of this secret vary depending on the object storage in use. For more information, see Secrets and TLS Configuration.

  3. Create a service account for the collector: 

    $ oc create sa collector -n openshift-logging
    Copy to Clipboard Toggle word wrap

  4. Allow the collector’s service account to write data to the LokiStack CR: 

    $ oc adm policy add-cluster-role-to-user logging-collector-logs-writer -z collector -n openshift-logging
    Copy to Clipboard Toggle word wrap
    Note

    The ClusterRole resource is created automatically during the Cluster Logging Operator installation and does not need to be created manually.

  5. To collect logs, use the service account of the collector by running the following commands: 

    $ oc adm policy add-cluster-role-to-user collect-application-logs -z collector -n openshift-logging
    Copy to Clipboard Toggle word wrap 
    $ oc adm policy add-cluster-role-to-user collect-audit-logs -z collector -n openshift-logging
    Copy to Clipboard Toggle word wrap 
    $ oc adm policy add-cluster-role-to-user collect-infrastructure-logs -z collector -n openshift-logging
    Copy to Clipboard Toggle word wrap
    Note

    The example binds the collector to all three roles (application, infrastructure, and audit), but by default, only application and infrastructure logs are collected. To collect audit logs, update your ClusterLogForwarder configuration to include them. Assign roles based on the specific log types required for your environment.

  6. Create a UIPlugin CR to enable the Log section in the Observe tab: 

    apiVersion: observability.openshift.io/v1alpha1
kind: UIPlugin
metadata:
  name: logging
spec:
  type: Logging
  logging:
    lokiStack:
      name: logging-loki
    Copy to Clipboard Toggle word wrap

  7. Create a ClusterLogForwarder CR to configure log forwarding: 

    apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  name: collector
  namespace: openshift-logging
spec:
  serviceAccount:
    name: collector
  outputs:
  - name: default-lokistack
    type: lokiStack
    lokiStack:
      authentication:
        token:
          from: serviceAccount
      target:
        name: logging-loki
        namespace: openshift-logging
    tls:
      ca:
        key: service-ca.crt
        configMapName: openshift-service-ca.crt
  pipelines:
  - name: default-logstore
    inputRefs:
    - application
    - infrastructure
    outputRefs:
    - default-lokistack
    Copy to Clipboard Toggle word wrap
    Note

    The dataModel field is optional and left unset (dataModel: "") by default. This allows the Cluster Logging Operator (CLO) to automatically select a data model. Currently, the CLO defaults to the ViaQ model when the field is unset, but this will change in future releases. Specifying dataModel: ViaQ ensures the configuration remains compatible if the default changes.

Verification

  • Verify that logs are visible in the Log section of the Observe tab in the OpenShift Container Platform web console.

4.2. Quick start with OpenTelemetry
Copy link

Important

The OpenTelemetry Protocol (OTLP) output log forwarder is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

To configure OTLP ingestion and enable the OpenTelemetry data model, follow these steps:

Prerequisites

  • Cluster administrator permissions

Procedure

  1. Install the Red Hat OpenShift Logging Operator, Loki Operator, and Cluster Observability Operator (COO) from OperatorHub.

  2. Create a LokiStack custom resource (CR) in the openshift-logging namespace: 

    apiVersion: loki.grafana.com/v1
kind: LokiStack
metadata:
  name: logging-loki
  namespace: openshift-logging
spec:
  managementState: Managed
  size: 1x.extra-small
  storage:
    schemas:
    - effectiveDate: '2024-10-01'
      version: v13
    secret:
      name: logging-loki-s3
      type: s3
  storageClassName: gp3-csi
  tenants:
    mode: openshift-logging
    Copy to Clipboard Toggle word wrap
    Note

    Ensure that the logging-loki-s3 secret is created beforehand. The contents of this secret vary depending on the object storage in use. For more information, see "Secrets and TLS Configuration".

  3. Create a service account for the collector: 

    $ oc create sa collector -n openshift-logging
    Copy to Clipboard Toggle word wrap

  4. Allow the collector’s service account to write data to the LokiStack CR: 

    $ oc adm policy add-cluster-role-to-user logging-collector-logs-writer -z collector
    Copy to Clipboard Toggle word wrap
    Note

    The ClusterRole resource is created automatically during the Cluster Logging Operator installation and does not need to be created manually.

  5. Allow the collector’s service account to collect logs: 

    $ oc project openshift-logging
    Copy to Clipboard Toggle word wrap 
    $ oc adm policy add-cluster-role-to-user collect-application-logs -z collector
    Copy to Clipboard Toggle word wrap 
    $ oc adm policy add-cluster-role-to-user collect-audit-logs -z collector
    Copy to Clipboard Toggle word wrap 
    $ oc adm policy add-cluster-role-to-user collect-infrastructure-logs -z collector
    Copy to Clipboard Toggle word wrap
    Note

    The example binds the collector to all three roles (application, infrastructure, and audit). By default, only application and infrastructure logs are collected. To collect audit logs, update your ClusterLogForwarder configuration to include them. Assign roles based on the specific log types required for your environment.

  6. Create a UIPlugin CR to enable the Log section in the Observe tab: 

    apiVersion: observability.openshift.io/v1alpha1
kind: UIPlugin
metadata:
  name: logging
spec:
  type: Logging
  logging:
    lokiStack:
      name: logging-loki
    Copy to Clipboard Toggle word wrap

  7. Create a ClusterLogForwarder CR to configure log forwarding: 

    apiVersion: observability.openshift.io/v1
kind: ClusterLogForwarder
metadata:
  name: collector
  namespace: openshift-logging
  annotations:
    observability.openshift.io/tech-preview-otlp-output: "enabled"
    1 
    
spec:
  serviceAccount:
    name: collector
  outputs:
  - name: loki-otlp
    type: lokiStack
    2 
    
    lokiStack:
      target:
        name: logging-loki
        namespace: openshift-logging
      dataModel: Otel
    3 
    
      authentication:
        token:
          from: serviceAccount
    tls:
      ca:
        key: service-ca.crt
        configMapName: openshift-service-ca.crt
  pipelines:
  - name: my-pipeline
    inputRefs:
    - application
    - infrastructure
    outputRefs:
    - loki-otlp
    Copy to Clipboard Toggle word wrap
    1
    Use the annotation to enable the Otel data model, which is a Technology Preview feature.
    2
    Define the output type as lokiStack.
    3
    Specifies the OpenTelemetry data model.
    Note

    You cannot use lokiStack.labelKeys when dataModel is Otel. To achieve similar functionality when dataModel is Otel, refer to "Configuring LokiStack for OTLP data ingestion".

Verification

  • Verify that OTLP is functioning correctly by going to Observe → OpenShift Logging → LokiStack → Writes in the OpenShift web console, and checking Distributor - Structured Metadata.

Legal Notice
Copy link

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, 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, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat