logger_handler(3)

🎀 logger_handler — the manual, but make it make sense

okay bestie, gather round, because this one is literally the blueprint for every logger handler in Erlang. It lives in kernel, and the module name is logger_handler. That's the whole name. Short, sweet, iconic. 💅

---

✨ NAME ✨

logger_handler — it's the behaviour module for logger handlers. Yes, behaviour with a u, we're fancy like that. 👑

---

🌸 DESCRIPTION 🌸

So here's the tea: logger_handler is the behaviour module for logger handlers. A logger handler is just a callback module — a little module full of callbacks — that gets called when a log event has passed all filters and is ready to be logged somewhere. Like, it survived the vibe check and now it gets to go live somewhere. ✨

For more info, go read Handlers in the Users Guide. That's where the lore lives.

👀 See Also

• logger_filters
• logger_formatter
• logger

---

💖 DATA TYPES 💖

config()

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()}}.

This is the handler configuration data for Logger. Here are the default values that just apply automatically, no questions asked:

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

And on top of those, Logger itself goes ahead and inserts these fields for you — the values come from the two first parameters you hand to logger:add_handler/3:

• id => HandlerId
• module => Module

⚠️ These two are read-only and cannot be changed in runtime. Not even a little. Don't try it. 🙈

Handler-specific configuration data gets inserted by the handler callback itself, in a sub structure that hangs off the field named config. If you wanna know what those specific configs look like, go peek at the logger_std_h and logger_disk_log_h manual pages. 🫶

And for the default configuration of this formatter? That's the logger_formatter manual page's job. Go say hi to it.

---

id()

id() :: atom().

A unique identifier for a handler instance. It's an atom, and it's that handler's name in the group chat. Only one of them can have it. 🦋

---

olp_config()

olp_config() ::
          #{sync_mode_qlen => non_neg_integer(),
            drop_mode_qlen => pos_integer(),
            flush_qlen => pos_integer(),
            burst_limit_enable => boolean(),
            burst_limit_max_count => pos_integer(),
            burst_limit_window_time => pos_integer(),
            overload_kill_enable => boolean(),
            overload_kill_qlen => pos_integer(),
            overload_kill_mem_size => pos_integer(),
            overload_kill_restart_after => non_neg_integer() |
infinity}.

This is your overload protection configuration — literally the handler's bodyguards. 🛡️

Wanna know all the details? Go read Protecting the Handler from Overload. The full story is over there, no cap.

---

🦋 CALLBACKS 🦋

adding_handler(Config1)

This one gets called on a temporary process when a new handler is about to be added. Its whole job is to verify the configuration and get all the resources the handler needs up and running. Basically the pre-game. ✨

The handler's identity is tied to the id key in Config1. That's how you know which handler you're dealing with.

If everything goes great? The callback can add any default values or internal state values it wants to the configuration, and then return the adjusted map as {ok,Config2}. Slay.

If the configuration is faulty, or the initiation just fails? The callback must return {error,Reason}. No hiding it. 😭

---

changing_config(SetOrUpdate, OldConfig, NewConfig)

Called on a temporary process when a handler's configuration is about to change. The vibe here is: verify the new config, and act on it. 👑

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

The handler identity is associated with the id key in OldConfig. (Yes, OldConfig, not NewConfig — read it again, bestie.)

Now, SetOrUpdate — this is the fun part:

• it has the value set if the configuration change came from a call to logger:set_handler_config/2,3
• it has the value update if it came from logger:update_handler_config/2,3

The handler can use this parameter to decide how it updates the value of the config field — y'know, the handler-specific configuration data. Typically:

• if SetOrUpdate equals set, then values that are not specified must be given their default values
• if SetOrUpdate equals update, then the values found in OldConfig must be used instead

If everything works out, the callback must return a possibly adjusted configuration as {ok,Config}.

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

---

filter_config(Config)

This one gets called whenever one of the Logger API functions for fetching the handler configuration gets called — for example, logger:get_handler_config/1. 🌸

What's it for? It lets the handler remove internal data fields from its configuration data before that data gets handed back to whoever asked. Privacy settings, but for config. 🙈

---

log(LogEvent, Config)

The moment we've all been waiting for. 🎉 This gets called when all primary filters and all handler filters for the handler in question have passed for the given log event.

Important: it's called on the client process — that is, the process that issued the log event. Not some background guy. The actual client.

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

The handler must log the event. That's literally its whole purpose, bestie.

The return value from this function is ignored by Logger. So don't stress about it. ✨

---

removing_handler(Config)

Called on a temporary process when a handler is about to be removed. Its purpose: release all resources used by the handler. Clean up your room before you leave. 🧹

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

The return value is ignored by Logger. Again. Logger is not nosy about return values.

---

okay that's the whole page!! every callback, every field, every default, all of it, accounted for. 🫶

this masterpiece was brought to you by Ericsson AB, from kernel 11.0.3, and it's the logger_handler(3) manual page — go forth and handle your logs, bestie, you're gonna eat 💅✨