View Source logger_handler behaviour (kernel v9.3)

logger_handler behavior module.

The behaviour module for logger handlers. A logger handler is a callback module that is called when a log event has passed all filters and is ready to be logged somewhere. For more information see Handlers in the Users Guide.

See Also

logger_filters, logger_formatter, logger

Summary

Types

config()

Handler configuration data for Logger. The following default values apply

id()

A unique identifier for a handler instance.

Callbacks

adding_handler(Config1)

This callback function is optional.

changing_config(SetOrUpdate, OldConfig, NewConfig)

This callback function is optional.

filter_config(Config)

This callback function is optional.

log(LogEvent, Config)

This callback function is mandatory.

removing_handler(Config)

This callback function is optional.

Types

Link to this type

config()

View Source (since OTP 27.0) 
-type config() ::
    #{id => id(),
      config => term(),
      level => logger:level() | all | none,
      module => module(),
      filter_default => log | stop,
      filters => [{logger:filter_id(), logger:filter()}],
      formatter => {module(), logger:formatter_config()}}.

Handler configuration data for Logger. The following default values apply:

  • level => all
  • filter_default => log
  • filters => []
  • formatter => {logger_formatter, DefaultFormatterConfig}

In addition to these, the following fields are automatically inserted by Logger, values taken from the two first parameters to logger:add_handler/3:

  • id => HandlerId
  • module => Module

These are read-only and cannot be changed in runtime.

Handler specific configuration data is inserted by the handler callback itself, in a sub structure associated with the field named config. See the logger_std_h and logger_disk_log_h manual pages for information about the specific configuration for these handlers.

See the logger_formatter manual page for information about the default configuration for this formatter.

Link to this type

id()

View Source (since OTP 27.0) 
-type id() :: atom().

A unique identifier for a handler instance.

Callbacks

Link to this callback

adding_handler(Config1)

View Source (optional) (since OTP 21.0) 
-callback adding_handler(Config1) -> {ok, Config2} | {error, Reason}
                  when Config1 :: config(), Config2 :: config(), Reason :: term().

This callback function is optional.

The function is called on a temporary process when a new handler is about to be added. The purpose is to verify the configuration and initiate all resources needed by the handler.

The handler identity is associated with the id key in Config1.

If everything succeeds, the callback function can add possible default values or internal state values to the configuration, and return the adjusted map in {ok,Config2}.

If the configuration is faulty, or if the initiation fails, the callback function must return {error,Reason}.

Link to this callback

changing_config(SetOrUpdate, OldConfig, NewConfig)

View Source (optional) (since OTP 21.2) 
-callback changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Config} | {error, Reason}
                   when
                       SetOrUpdate :: set | update,
                       OldConfig :: config(),
                       NewConfig :: config(),
                       Config :: config(),
                       Reason :: term().

This callback function is optional.

The function is called on a temporary process when the configuration for a handler is about to change. The purpose is to verify and act on the new configuration.

OldConfig is the existing configuration and NewConfig is the new configuration.

The handler identity is associated with the id key in OldConfig.

SetOrUpdate has the value set if the configuration change originates from a call to logger:set_handler_config/2,3, and update if it originates from logger:update_handler_config/2,3. The handler can use this parameter to decide how to update the value of the config field, that is, the handler specific configuration data. Typically, if SetOrUpdate equals set, values that are not specified must be given their default values. If SetOrUpdate equals update, the values found in OldConfig must be used instead.

If everything succeeds, the callback function must return a possibly adjusted configuration in {ok,Config}.

If the configuration is faulty, the callback function must return {error,Reason}.

Link to this callback

filter_config(Config)

View Source (optional) (since OTP 21.2) 
-callback filter_config(Config) -> FilteredConfig when Config :: config(), FilteredConfig :: config().

This callback function is optional.

The function is called when one of the Logger API functions for fetching the handler configuration is called, for example logger:get_handler_config/1.

It allows the handler to remove internal data fields from its configuration data before it is returned to the caller.

Link to this callback

log(LogEvent, Config)

View Source (since OTP 21.0) 
-callback log(LogEvent, Config) -> term() when LogEvent :: logger:log_event(), Config :: config().

This callback function is mandatory.

The function is called when all primary filters and all handler filters for the handler in question have passed for the given log event. It is called on the client process, that is, the process that issued the log event.

The handler identity is associated with the id key in Config.

The handler must log the event.

The return value from this function is ignored by Logger.

Link to this callback

removing_handler(Config)

View Source (optional) (since OTP 21.0) 
-callback removing_handler(Config) -> ok when Config :: config().

This callback function is optional.

The function is called on a temporary process when a handler is about to be removed. The purpose is to release all resources used by the handler.

The handler identity is associated with the id key in Config.

The return value is ignored by Logger.