Versions Compared

Old Version 9

changes.mady.by.user Stanislav Kozlovski

Saved on

compared with

New Version 10

changes.mady.by.user Stanislav Kozlovski

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Remove option to turn logs OFF

...

To differentiate between the normal Kafka config settings and the application's log level settings, we will introduce a new resource type - BROKER_LOGGERS

public final class ConfigResource {
 
    /**
     * Type of resource.
     */
    public enum Type {
        BROKER_LOGGER((byte) 8), BROKER((byte) 4), TOPIC((byte) 2), UNKNOWN((byte) 0);
    }
}

When resource_type=BROKER_LOGGER:

  • we will use the existing ACL for the Cluster resource (as used in IncrementalAlterConfigs/DescribeConfigs operations).
  • we will only support one of eight values seven values for the value of a config - the log levels (ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF)

Log Level Definitions

Let's define the log levels we support and the syslog severity level (as defined in RFC-5424) they correspond to:

ALL - intended to enable all logging. all syslog levels
TRACE - intended to enable TRACE logs - syslog level 7 and above
DEBUG - intended to enable DEBUG logs - syslog level 7 and above
INFO - intended to enable INFO logs - syslog level 6 and above
WARN - intended to enable WARN logs - syslog level 4 and above
ERROR - intended to enable ERROR logs - syslog level 3 and above
FATAL - intended to enable FATAL logs - syslog level 0


OFF - intended to turn off all logging


To have these levels defined in code, we will create a new public class called LogLevelConfig, intended to be used by the AdminClient

...

Code Block
languagejava
package org.apache.kafka.common.config;

/**
 * This class holds definitions for log level configurations related to Kafka's application logging. See KIP-412 for additional information
 */
public class LogLevelConfig {
    /*
     * NOTE: DO NOT CHANGE EITHER CONFIG NAMES AS THESE ARE PART OF THE PUBLIC API AND CHANGE WILL BREAK USER CODE.
     */

    /**
     * The <code>OFF</code> has the highest possible rank and is
     * intended to turn off logging.
     * WARNING: This is not recommended for use
     */
    public static final String OFF_LOG_LEVEL = "OFF"; BREAK USER CODE.
     */

    /**
     * The <code>FATAL</code> level designates a very severe error
     * that will lead the Kafka broker to abort.
     */
    public static final String FATAL_LOG_LEVEL = "FATAL";

    /**
     * The <code>ERROR</code> level designates error events that
     * might still allow the broker to continue running.
     */
    public static final String ERROR_LOG_LEVEL = "ERROR";

    /**
     * The <code>WARN</code> level designates potentially harmful situations.
     */
    public static final String WARN_LOG_LEVEL = "WARN";

    /**
     * The <code>INFO</code> level designates informational messages
     *      that highlight normal Kafka events at a coarse-grained level
     */
    public static final String INFO_LOG_LEVEL = "INFO";

    /**
     * The <code>DEBUG</code> Level designates fine-grained
     * informational events that are most useful to debug Kafka
     */
    public static final String DEBUG_LOG_LEVEL = "DEBUG";

    /**
     * The <code>TRACE</code> Level designates finer-grained
     * informational events than the <code>DEBUG</code level.
     */
    public static final String TRACE_LOG_LEVEL = "TRACE";

    /**
     * The <code>ALL</code> has the lowest possible rank and is intended to turn on all logging.
     */
    public static final String ALL_LOG_LEVEL = "ALL";
}

...

We will add a new DYNAMIC_BROKER_LOGGER_CONFIG type to the ConfigSource enum

public enum ConfigSource {

  DYNAMIC_BROKER_LOGGER_CONFIG, // dynamic broker logger config that is configured for a specific broker <--- NEW


  DYNAMIC_TOPIC_CONFIG, // dynamic topic config that is configured for a specific topic
  DYNAMIC_BROKER_CONFIG, // dynamic broker config that is configured for a specific broker
  DYNAMIC_DEFAULT_BROKER_CONFIG, // dynamic broker config that is configured as default for all brokers in the cluster
  STATIC_BROKER_CONFIG, // static broker config provided as broker properties at start up (e.g. server.properties file)
  DEFAULT_CONFIG, // built-in default configuration for configs that have a default value
  UNKNOWN // source unknown e.g. in the ConfigEntry used for alter requests where source is not set
}


Request/Response Overview

We will not be modifying the DescribeConfigs/IncrementalAlterConfigs request/response.
Let's go over the expected semantics when using them with the new resource type.

DescribeConfigs

DescribeConfigs Request (Version: 2) => [resource [config_name]] include_synonyms
    resource => resource_type resource_name
        resource_type => INT8 # BROKER_LOGGER (8)
        resource_name => STRING # ID of broker
    config_name => STRING
    include_synonyms => BOOLEAN # ignored
 
DescribeConfigs Response (Version: 2) => throttle_time_ms entities
    throttle_time_ms => INT32
    entities => error_code error_message resource configs
        error_code => INT16
        error_message => STRING
        resource => resource_type resource_name
            resource_type => INT8 # BROKER_LOGGER (8)
            resource_name => STRING # ID of broker
        configs => [config_entry synonym]
            config_entry =>
                config_name => STRING # logger name - e.g kafka.server.ReplicaManager
                config_value => STRING # log level - e.g INFO. Null if not set explicitly yet
                read_only => BOOLEAN # false always
                config_source => INT8 # (DYNAMIC_BROKER_LOGGER_CONFIG)
                is_sensitive => BOOLEAN # false always
            synonym => # empty always
                config_name => STRING
                config_value => NULLABLE_STRING
                config_source => INT8

Request semantics (as defined in KIP-133) are conserved where applicable:

...

SET: Set the log level to the desired value
REMOVE: Sets the log level to the same as the root logger's

IncrementalAlterConfigsOp => INT8
0: SET
1: REMOVE # sets log level to NULL
2: APPEND # NOT SUPPORTED
3: SUBTRACT # NOT SUPPORTED
  
IncrementalAlterConfigsRequest (Version: 0) => [resources] validate_only
 validate_only => BOOLEAN
 resources => resource_type resource_name [configs]
    resource_type => INT8 # BROKER_LOGGER (8)
    resource_name => STRING # ID of broker
    configs => config_name config_op config_value
        config_name => STRING
        config_op => INT8 # support SET and APPEND only
        config_value => NULLABLE_STRING
 
IncrementalAlterConfigsResponse (Version: 0) => [responses] 
  responses => resource_type resource_name error_code error_message
  resource_type => INT8 # BROKER_LOGGER (8)
  resource_name => STRING # ID of broker
  error_code => INT16
  error_message => NULLABLE_STRING

Request semantics (as defined in KIP-133 and KIP-339) are conserved where applicable:

...

kafka-configs.sh will be extended to support the new resource type via --entity-type broker-logger.

Examples:

bin/kafka-configs.sh --bootstrap-server localhost:9092 --describe --entity-type broker-logger --entity-name 0  // show all the log levels for broker 0
 
bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --add-config "kafka.server.ReplicaManager=WARN,kafka.server.KafkaApis=DEBUG" --entity-type broker-logger --entity-name 0  // set some log levels for broker 0
 
bin/kafka-configs.sh --bootstrap-server localhost:9092 --alter --delete-config kafka.server.ReplicaManager --entity-type broker-logger --entity-name 0 // will set the log level to NULL


Compatibility, Deprecation, and Migration Plan

...

  1. Extend Kafka's JmxTool class to support changing log levels dynamically
    1. Does not properly address the concerns outlined in the Motivation section 
      1. Can abstract away a bit of the complexity but still has the fundamental flaws of no security and not being easy to use
  2. Create new Admin API commands for reading and altering log levels
    1. Will result in more boilerplate and some code duplication.
    2. Will result in seemingly needless Admin API command bloat
    3. Altering log levels can be seen as a form of altering configurations and seems intuitive use the same API
    4. Will require separate Policy class
  3. Add new config_type field in Alter/Describe request/responses or new map of logger=>log_level 
    1. Results in more code and field bloat in request/response without clear benefits of extendability
  4. Support turning log levels to OFF
    1. Log4j supports a log level called OFF. We decided to not expose this as there is never a compelling reason to turn off application logs.