Logging

This page explains how to configure and manage logging in the Camunda 8 Self-Managed Orchestration Cluster, which includes Zeebe, Operate, Tasklist, and Admin. All components use the Log4j2 framework.

You can configure log levels, output formats, appenders, and adjust logging dynamically at runtime.

Default Log4j2 configuration

The default log4j2.xml (Zeebe, Operate, Tasklist, Admin) representation:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration xmlns="https://logging.apache.org/xml/ns"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="
                   https://logging.apache.org/xml/ns
                   https://logging.apache.org/xml/ns/log4j-config-2.xsd" status="WARN" shutdownHook="disable">
  <Properties>
    <Property name="log.path" value="${sys:app.home}/logs" />
    <Property name="log.pattern" value="[%d{yyyy-MM-dd HH:mm:ss.SSS}] [%t] %notEmpty{[%X] }%-5level \t%logger{36} - %msg%n" />
    <Property name="log.stackdriver.serviceName" value="${env:ZEEBE_LOG_STACKDRIVER_SERVICENAME:-${env:OPERATE_LOG_STACKDRIVER_SERVICENAME:-${env:OPTIMIZE_LOG_STACKDRIVER_SERVICENAME:-${env:TASKLIST_LOG_STACKDRIVER_SERVICENAME:-}}}}"/>
    <Property name="log.stackdriver.serviceVersion" value="${env:ZEEBE_LOG_STACKDRIVER_SERVICEVERSION:-${env:OPERATE_LOG_STACKDRIVER_SERVICEVERSION:-${env:OPTIMIZE_LOG_STACKDRIVER_SERVICEVERSION:-${env:TASKLIST_LOG_STACKDRIVER_SERVICEVERSION:-}}}}"/>
  </Properties>

  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout
        pattern="${log.pattern}"/>
    </Console>

    <Console name="Stackdriver" target="SYSTEM_OUT">
      <JsonTemplateLayout charset="UTF-8"
        eventTemplateUri="classpath:logging/StackdriverLayout.json"
        locationInfoEnabled="true"
        stackTraceEnabled="true"/>
    </Console>

    <Select>
      <EnvironmentArbiter propertyName="CAMUNDA_LOG_FILE_APPENDER_ENABLED" propertyValue="false">
        <Null name="RollingFile" />
      </EnvironmentArbiter>
      <DefaultArbiter>
        <RollingFile name="RollingFile" fileName="${log.path}/zeebe.log"
          filePattern="${log.path}/zeebe-%d{yyyy-MM-dd}-%i.log.gz">
          <PatternLayout pattern="${log.pattern}" />
          <Policies>
            <TimeBasedTriggeringPolicy/>
            <SizeBasedTriggeringPolicy size="250 MB"/>
          </Policies>
        </RollingFile>
      </DefaultArbiter>
    </Select>
  </Appenders>

  <Loggers>
    <Logger name="io.camunda" level="${env:CAMUNDA_LOG_LEVEL:-INFO}" />
    <Logger name="io.camunda.zeebe" level="${env:ZEEBE_LOG_LEVEL:-${env:CAMUNDA_LOG_LEVEL:-INFO}}" />
    <Logger name="io.atomix" level="${env:ATOMIX_LOG_LEVEL:-${env:CAMUNDA_LOG_LEVEL:-INFO}}" />
    <Logger name="org.elasticsearch" level="${env:ES_LOG_LEVEL:-WARN}" />
    <Logger name="org.springframework" level="INFO" />

    <Root level="WARN">
      <AppenderRef ref="RollingFile" />

      <!-- remove to disable console logging -->
      <AppenderRef ref="${env:ZEEBE_LOG_APPENDER:-${env:OPERATE_LOG_APPENDER:-${env:OPTIMIZE_LOG_APPENDER:-${env:TASKLIST_LOG_APPENDER:-Console}}}}"/>
    </Root>
  </Loggers>

</Configuration>

note

This is a simplified example. The actual log4j2.xml may include additional appenders, different file paths, or slightly different patterns.
See the full logging documentation for the official default file and additional settings.

Environment variables

Purpose	Variable	Component(s)	Example / Notes
Global log level	CAMUNDA_LOG_LEVEL	All	DEBUG, INFO, WARN, etc.
Zeebe package level	ZEEBE_LOG_LEVEL	Zeebe	Overrides global level
Atomix / clustering	ATOMIX_LOG_LEVEL	Atomix / Raft	Defaults to CAMUNDA_LOG_LEVEL, otherwise INFO
Elasticsearch logs	ES_LOG_LEVEL	org.elasticsearch

JSON logging appenders

Appender	Description	Enable / Variable
Console	Standard text output	*_LOG_APPENDER=Console
Stackdriver (JSON)	JSON output for Google Cloud / Stackdriver	*_LOG_APPENDER=Stackdriver
RollingFile	Writes logs to a rotating file, enabled by default	Disable with CAMUNDA_LOG_FILE_APPENDER_ENABLED=false

Pattern layout/format

• The default layout shows the full date and time, thread name, MDC context, log level, logger name, and message.

Default pattern:

[%d{yyyy-MM-dd HH:mm:ss.SSS}] [%t] %notEmpty{[%X] }%-5level \t%logger{36} - %msg%n

Changing log level at runtime

You can adjust log levels dynamically using Spring Boot Actuator endpoints:

curl 'http://localhost:9600/actuator/loggers/io.camunda' \
  -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"configuredLevel":"DEBUG"}'

Replace io.camunda with the logger you want to adjust.

Sensitive data

By default, loggers that may handle sensitive information (e.g., variable values, actor names) are set to INFO.
To capture more detail (DEBUG or TRACE), explicitly configure those loggers via their logger names or component-specific variables.

warning

Enabling verbose logging may expose sensitive data. Use debug/trace levels only temporarily for troubleshooting.

Best practices

• Always check the inline default configuration before customizing.
• Use component-specific *_LOG_LEVEL and *_LOG_APPENDER variables for fine-grained control.
• Select the Stackdriver appender only when you need JSON output; the console appender is simpler for stdout logs. Disable the RollingFile appender with CAMUNDA_LOG_FILE_APPENDER_ENABLED=false if you collect logs from stdout only.
• Monitor logging setup across environments (dev/test/prod) to avoid surprises caused by log verbosity.