How to Configure Logging

This guide shows you how to set the log level for an Axual component, how to raise the level for one Java package rather than the whole service, and which components set their log levels somewhere else.

Type

How-to guide

Goal

Change the log level or log pattern of an Axual component.

Audience

Platform Operator who can edit the component’s values.yaml and apply it.

When to use

Use this guide when a component is not logging enough to diagnose a problem, or is logging so much that the useful lines are buried.

Most Axual Platform components are Java based and log through the Logback library, which is what makes a level change take effect without a restart.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Permission to edit the component’s values.yaml and apply it, whether through Helm directly or through the repository your deployment tool watches.

  • Permission to edit Kubernetes objects in the namespace, for the in-place path only.

Tools and versions required

You need the following tools:

  • helm >= 3.12, or access to the CI/CD pipeline that applies the values.

  • kubectl >= 1.28, for the in-place path only.

Resources that must exist before starting

The following must already exist:

  • The component, already installed. This guide changes an existing deployment rather than creating one.

Set the log level for a component

Add a logging block to the component’s section of values.yaml and apply it. Every component except the Apache Kafka broker picks up a new level without restarting, so a level change costs nothing but a redeploy.

component: (1)
  logging: (2)
    pattern: "%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX, UTC} ${LOG_LEVEL_PATTERN:-%5p} ${PID:- } --- [%15.15t] [traceId=%X{traceId}, spanId=%X{spanId}] %-40.40logger{39} : %m%n"
    rootLoglevel: INFO (3)
    loggers:
      io.axual: INFO
      io.axual.auditing.logging: INFO
      org.apache.catalina.core.StandaloneService: DEBUG
1 The component’s key in values.yaml, for example platform-manager or api-gateway.
2 Holds the log levels and, optionally, the log pattern.
3 Applies to every logger that no entry under loggers overrides.

Apply the change the way this component is normally deployed. Deployment Strategy describes both routes.

Leave pattern alone unless you have a reason to change it. Downstream log centralisation tools and alerting rules parse the pattern, so changing it breaks them silently.

Raise the level for one package only

Setting rootLoglevel to DEBUG puts every logger in the service at DEBUG, which on a busy component produces more output than anyone can read. Set an entry under loggers instead, keyed by the Java package or even the class you are interested in.

component:
  logging:
    rootLoglevel: INFO
    loggers:
      io.axual.platformmanager.security: DEBUG

An entry under loggers always wins over rootLoglevel, so the rest of the service stays at INFO.

Change a level without a full GitOps cycle

While diagnosing a live problem, edit the Kubernetes object directly rather than pushing a values change through review and synchronisation. The next synchronisation reverts the edit, which is what makes this safe to do and unsafe to rely on.

kubectl edit configmap <CONFIGMAP_NAME> --namespace <NAMESPACE>
Replace every <VALUE> placeholder with your own value before running a command.

Once the diagnosis is done, put the change into values.yaml if it is meant to stay. GitOps & CI/CD covers when stepping outside the workflow is worth it.

Verify the new level is in effect

A component reloads its logging configuration without announcing it, so read the output and confirm the new level appears. Every component except the Apache Kafka broker picks the level up while running; the broker needs its pod restarted first.

kubectl logs <POD_NAME> --namespace <NAMESPACE> --tail=20 | grep DEBUG

Expected result: lines from the package you raised, each carrying DEBUG where the log pattern places the level. Substitute the level you set if it is not DEBUG.

An empty result means the change did not reach the pod, or the package name under loggers does not match the one the component logs under. Read the configuration the pod is running with to tell the two apart:

kubectl get configmap <CONFIGMAP_NAME> --namespace <NAMESPACE> --output yaml

Components that configure logging elsewhere

Four components do not read the logging block above, because they are not Axual-built Java services:

  • The Apache Kafka broker has its own logging section, and unlike the others it needs a restart. See the Logging section of the Apache Kafka page.

  • Keycloak, HashiCorp Vault and Apicurio Registry each configure logging through their own chart values, so their log output is also formatted differently from the Axual components.