Package org.elasticsearch.common.logging

Class DeprecationLogger

java.lang.Object
org.elasticsearch.common.logging.DeprecationLogger
public class DeprecationLogger extends Object
A logger that logs deprecation notices. Logger should be initialized with a class or name which will be used for deprecation logger. For instance DeprecationLogger.getLogger("org.elasticsearch.test.SomeClass") will result in a deprecation logger with name org.elasticsearch.deprecation.test.SomeClass. This allows to use a deprecation logger defined in log4j2.properties.

Logs are emitted at the custom CRITICAL level, and routed wherever they need to go using log4j. For example, to disk using a rolling file appender, or added as a response header using HeaderWarningAppender.

Deprecation messages include a key, which is used for rate-limiting purposes. The log4j configuration uses RateLimitingFilter to prevent the same message being logged repeatedly in a short span of time. This key is combined with the X-Opaque-Id request header value, if supplied, which allows for per-client message limiting.

  • Field Details

    • CRITICAL

      public static org.apache.logging.log4j.Level CRITICAL
      Deprecation messages are logged at this level. More serious than WARN by 1, but less serious than ERROR

  • Method Details

    • getLogger

      public static DeprecationLogger getLogger(Class<?> aClass)
      Creates a new deprecation logger for the supplied class. Internally, it delegates to getLogger(String), passing the full class name.

    • getLogger

      public static DeprecationLogger getLogger(String name)
      Creates a new deprecation logger based on the parent logger. Automatically prefixes the logger name with "deprecation", if it starts with "org.elasticsearch.", it replaces "org.elasticsearch" with "org.elasticsearch.deprecation" to maintain the "org.elasticsearch" namespace.

    • initialize

      public static void initialize(Settings nodeSettings)
      The DeprecationLogger uses the "deprecation.skip_deprecated_settings" setting to decide whether to log a deprecation for a setting. This is a node setting. This method initializes the DeprecationLogger class with the node settings for the node in order to read the "deprecation.skip_deprecated_settings" setting. This only needs to be called once per JVM. If it is not called, the default behavior is to assume that the "deprecation.skip_deprecated_settings" setting is not set.
      Parameters:
      nodeSettings - The settings for this node

    • critical

      public DeprecationLogger critical(DeprecationCategory category, String key, String msg, Object... params)
      Logs a message at the CRITICAL level. This log will indicate that a change will break in next version. The message is also sent to the header warning logger, so that it can be returned to the client.

    • warn

      public DeprecationLogger warn(DeprecationCategory category, String key, String msg, Object... params)
      Logs a message at the Level.WARN level for less critical deprecations that won't break in next version. The message is also sent to the header warning logger, so that it can be returned to the client.