View Source logger_std_h (kernel v10.1.2)
Standard handler for Logger.
This is the standard handler for Logger. Multiple instances of this handler can
be added to Logger, and each instance prints logs to
standard_io
,
standard_error
, or to file.
The handler has an overload protection mechanism that keeps the handler process
and the Kernel application alive during high loads of log events. 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.
Defaults to
standard_io
, unless parameterfile
is given, in which case it defaults tofile
.file =
file:filename/0
- This specifies the name of the log file when the handler is of typefile
.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, seefile:open/2
. Ifmodes
are not specified, the default list used is[raw,append,delayed_write]
. Ifmodes
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
orexclusive
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}
.The value is set when the handler is added, and it cannot be changed in runtime.
Defaults to
[raw,append,delayed_write]
.- If
max_no_bytes =
pos_integer/0
| infinity
- This parameter specifies if the log file should be rotated or not. The valueinfinity
means the log file will grow indefinitely, 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 ifmax_no_bytes
is set to an integer value.The log archives are named
FileName.0
,FileName.1
, ...FileName.N
, whereFileName
is the name of the current log file.FileName.0
is the newest of the archives. The maximum value forN
is the value ofmax_no_files
minus 1.Notice that setting this value to
0
does not turn off rotation. It only specifies that no archives are kept.Defaults to
0
.compress_on_rotate =
boolean/0
- This parameter specifies if the rotated log file archives shall be compressed or not. If set totrue
, all archives are compressed withgzip
, and renamed toFileName.N.gz
compress_on_rotate
has no meaning ifmax_no_bytes
has the valueinfinity
.Defaults to
false
.file_check =
non_neg_integer/0
- Whenlogger_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.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 thanN
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 thefilesync/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.
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
Summary
Functions
Write buffered data to disk.