1logger_std_h(3)            Erlang Module Definition            logger_std_h(3)
2
3
4

NAME

6       logger_std_h - Standard handler for Logger.
7

DESCRIPTION

9       This  is  the  standard  handler for Logger. Multiple instances of this
10       handler can be added to Logger, and each instance prints logs to  stan‐
11       dard_io, standard_error, or to file.
12
13       The handler has an overload protection mechanism that keeps the handler
14       process and the Kernel application  alive  during  high  loads  of  log
15       events.  How overload protection works, and how to configure it, is de‐
16       scribed in the User's Guide.
17
18       To add a new instance of  the  standard  handler,  use  logger:add_han‐
19       dler/3.  The  handler configuration argument is a map which can contain
20       general configuration parameters, as documented in  the  User's  Guide,
21       and  handler  specific parameters. The specific data is stored in a sub
22       map with the key config, and can contain the following parameters:
23
24         type = standard_io | standard_error | file | {device, io:device()}:
25           Specifies the log destination.
26
27           The value is set when the  handler  is  added,  and  it  cannot  be
28           changed in runtime.
29
30           Defaults  to  standard_io, unless parameter file is given, in which
31           case it defaults to file.
32
33         file = file:filename():
34           This specifies the name of the log file when the handler is of type
35           file.
36
37           The  value  is  set  when  the  handler  is added, and it cannot be
38           changed in runtime.
39
40           Defaults to the same name as the handler identity, in  the  current
41           directory.
42
43         modes = [file:mode()]:
44           This specifies the file modes to use when opening the log file, see
45           file:open/2. If modes are not specified, the default list  used  is
46           [raw,append,delayed_write].  If  modes  are specified, the list re‐
47           places the default modes list with the following adjustments:
48
49           *
50              If raw is not found in the list, it is added.
51
52           *
53              If none of write, append or exclusive is found in the list,  ap‐
54             pend is added.
55
56           * If  none  of delayed_write or {delayed_write,Size,Delay} is found
57             in the list, delayed_write is added.
58
59           Log files are always UTF-8 encoded. The encoding cannot be  changed
60           by setting the mode {encoding,Encoding}.
61
62           The  value  is  set  when  the  handler  is added, and it cannot be
63           changed in runtime.
64
65           Defaults to [raw,append,delayed_write].
66
67         max_no_bytes = pos_integer() | infinity:
68           This parameter specifies if the log file should be rotated or  not.
69           The value infinity means the log file will grow indefinitely, while
70           an integer value specifies at which file size (bytes) the  file  is
71           rotated.
72
73           Defaults to infinity.
74
75         max_no_files = non_neg_integer():
76           This parameter specifies the number of rotated log file archives to
77           keep. This has meaning only if max_no_bytes is set  to  an  integer
78           value.
79
80           The  log archives are named FileName.0, FileName.1, ... FileName.N,
81           where FileName is the name of the current log file.  FileName.0  is
82           the newest of the archives. The maximum value for N is the value of
83           max_no_files minus 1.
84
85           Notice that setting this value to 0 does not turn off rotation.  It
86           only specifies that no archives are kept.
87
88           Defaults to 0.
89
90         compress_on_rotate = boolean():
91           This  parameter specifies if the rotated log file archives shall be
92           compressed or not. If set to true, all archives are compressed with
93           gzip, and renamed to FileName.N.gz
94
95           compress_on_rotate has no meaning if max_no_bytes has the value in‐
96           finity.
97
98           Defaults to false.
99
100         file_check = non_neg_integer():
101           When logger_std_h logs to a file, it reads the file information  of
102           the  log  file  prior to each write operation. This is to make sure
103           the file still exists and has the same inode as when it was opened.
104           This  implies some performance loss, but ensures that no log events
105           are lost in the case when the file has been removed or  renamed  by
106           an external actor.
107
108           In  order  to allow minimizing the performance loss, the file_check
109           parameter can be set to a positive integer value,  N.  The  handler
110           will  then  skip  reading the file information prior to writing, as
111           long as no more than N milliseconds have passed since it  was  last
112           read.
113
114           Notice  that  the  risk  of  loosing  log  events  grows  when  the
115           file_check value grows.
116
117           Defaults to 0.
118
119         filesync_repeat_interval = pos_integer() | no_repeat:
120           This value, in milliseconds, specifies how often the handler does a
121           file sync operation to write buffered data to disk. The handler at‐
122           tempts the operation repeatedly, but only performs a  new  sync  if
123           something has actually been logged.
124
125           If  no_repeat  is set as value, the repeated file sync operation is
126           disabled, and it is the operating system  settings  that  determine
127           how  quickly  or  slowly data is written to disk. The user can also
128           call the filesync/1 function to perform a file sync.
129
130           Defaults to 5000 milliseconds.
131
132       Other configuration parameters exist, to be used  for  customizing  the
133       overload protection behaviour. The same parameters are used both in the
134       standard handler and the disk_log handler, and are  documented  in  the
135       User's Guide.
136
137       Notice  that  if  changing the configuration of the handler in runtime,
138       the type, file, or modes parameters must not be modified.
139
140       Example of adding a standard handler:
141
142       logger:add_handler(my_standard_h, logger_std_h,
143                          #{config => #{file => "./system_info.log",
144                                        filesync_repeat_interval => 1000}}).
145
146
147       To set the default handler, that starts initially with the  Kernel  ap‐
148       plication, to log to file instead of standard_io, change the Kernel de‐
149       fault logger configuration. Example:
150
151       erl -kernel logger '[{handler,default,logger_std_h,
152                             #{config => #{file => "./log.log"}}}]'
153
154
155       An example of how to replace the standard handler with a disk_log  han‐
156       dler at startup is found in the logger_disk_log_h manual.
157

EXPORTS

159       filesync(Name) -> ok | {error, Reason}
160
161              Types:
162
163                 Name = atom()
164                 Reason = handler_busy | {badarg, term()}
165
166              Write buffered data to disk.
167

SEE ALSO

169       logger(3), logger_disk_log_h(3)
170
171
172
173Ericsson AB                      kernel 8.1.3                  logger_std_h(3)
Impressum