logger_std_h(3)

💖 logger_std_h — the standard handler for Logger, bestie 💖

okay so this is a page from the Erlang Module Definition manual manual (the kernel one, iykyk), and it's all about logger_std_h, which is literally the main character of Erlang logging. buckle up. 🎀

---

✨ NAME ✨

logger_std_h — Standard handler for Logger. that's it, that's the name, slay. 💅

---

🌸 DESCRIPTION 🌸

okay so picture this: this is the standard handler for Logger. you can add multiple instances of this handler to Logger, and each instance prints logs to standard_io, standard_error, or to file. like, as many as you want, all doing their own lil thing. 🦋

the handler has an overload protection mechanism that keeps the handler process and the Kernel application alive during high loads of log events. so when everything is on fire and everyone is screaming in the group chat, this thing keeps its composure. no cap. how overload protection works and how to configure it is described in the User's Guide.

to add a new instance of the standard handler, use logger:add_handler/3. the handler configuration argument is a map which can contain general configuration parameters, as documented in the User's Guide, and handler specific parameters. the specific data is stored in a sub map with the key config, and can contain the following parameters:

• type = io:standard_io/0 | io:standard_error/0 | file | {device, io:device/0} — specifies the log destination.

The value is set when the handler is added, and it cannot be changed in runtime. (pick your lane and stay in it, periodt.)

Defaults to standard_io, unless parameter file is given, in which case it defaults to file.

• file = file:filename/0 — this specifies the name of the log file when the handler is of type file.

The value is set when the handler is added, and it cannot be changed in runtime.

Defaults to the same name as the handler identity, in the current directory.

• modes = [ file:mode/0 ] — this specifies the file modes to use when opening the log file, see file:open/2. if modes are not specified, the default list used is [raw,append,delayed_write]. if modes are specified, the list replaces the default modes list with the following adjustments:
  • If raw is not found in the list, it is added.
  • If none of write, append or exclusive is found in the list, append is added.
  • If none of delayed_write or {delayed_write,Size,Delay} is found in the list, delayed_write is added.

Log files are always UTF-8 encoded. the encoding cannot be changed by setting the mode {encoding,Encoding}. 😭 not negotiable, she said what she said.

The value is set when the handler is added, and it cannot be changed in runtime.

Defaults to [raw,append,delayed_write].

• max_no_bytes = pos_integer/0 | infinity — this parameter specifies if the log file should be rotated or not. the value infinity means the log file will grow indefinitely (forever, she's huge), while an integer value specifies at which file size (bytes) the file is rotated.

Defaults to infinity.

• max_no_files = non_neg_integer/0 — this parameter specifies the number of rotated log file archives to keep. this has meaning only if max_no_bytes is set to an integer value.

the log archives are named FileName.0, FileName.1, ... FileName.N, where FileName is the name of the current log file. FileName.0 is the newest of the archives. the maximum value for N is the value of max_no_files minus 1.

Notice that setting this value to 0 does not turn off rotation. it only specifies that no archives are kept. 💀 do not get this twisted.

Defaults to 0.

• compress_on_rotate = boolean/0 — this parameter specifies if the rotated log file archives shall be compressed or not. if set to true, all archives are compressed with gzip, and renamed to FileName.N.gz.

compress_on_rotate has no meaning if max_no_bytes has the value infinity.

Defaults to false.

• file_check = non_neg_integer/0 — when logger_std_h logs to a file, it reads the file information of the log file prior to each write operation. this is to make sure the file still exists and has the same inode as when it was opened. this implies some performance loss, but ensures that no log events are lost in the case when the file has been removed or renamed by an external actor. (protect the data at all costs, bestie 🫶)

in order to allow minimizing the performance loss, the file_check parameter can be set to a positive integer value, N. the handler will then skip reading the file information prior to writing, as long as no more than N milliseconds have passed since it was last read.

Notice that the risk of losing log events grows when the file_check value grows. ⚠️

Defaults to 0.

• filesync_repeat_interval = pos_integer/0 | no_repeat — this value, in milliseconds, specifies how often the handler does a file sync operation to write buffered data to disk. the handler attempts the operation repeatedly, but only performs a new sync if something has actually been logged.

if no_repeat is set as value, the repeated file sync operation is disabled, and it is the operating system settings that determine how quickly or slowly data is written to disk. the user can also call the filesync/1 function to perform a file sync. ✨

Defaults to 5000 milliseconds.

other configuration parameters exist, to be used for customizing the overload protection behaviour. the same parameters are used both in the standard handler and the disk_log handler, and are documented in the User's Guide.

Notice that if changing the configuration of the handler in runtime, the type, file, or modes parameters must not be modified. like, don't touch those three, they're locked in. 🔒

---

🍓 adding a standard handler, the example

Example of adding a standard handler:

logger:add_handler(my_standard_h, logger_std_h,
                   #{config => #{file => "./system_info.log",
                                 filesync_repeat_interval => 1000}}).

to set the default handler, that starts initially with the Kernel application, to log to file instead of standard_io, change the Kernel default logger configuration. Example:

erl -kernel logger '[{handler,default,logger_std_h,
                      #{config => #{file => "./log.log"}}}]'

an example of how to replace the standard handler with a disk_log handler at startup is found in the logger_disk_log_h manual. 👑

---

🌈 See Also

logger, logger_disk_log_h

---

👑 FUNCTIONS 👑

💜 filesync(Name) -> ok | {error, Reason}

filesync(Name) -> ok | {error, Reason}
                  when
                      Name :: atom(),
                      Reason :: handler_busy | {badarg, term()}.

write buffered data to disk. that's the whole job and she does it flawlessly. ✨

---

and that's the page, bestie!! 💖 this manual moment was brought to you by the icons at Ericsson AB, shipping it with kernel 11.0.3 — go forth and log responsibly, mwah 🎀💅🦋