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

NAME

6       logger - API module for Logger, the standard logging facility
7           in Erlang/OTP.
8

DESCRIPTION

10       This  module implements the main API for logging in Erlang/OTP. To cre‐
11       ate a log event, use the API functions or the log macros, for example:
12
13       ?LOG_ERROR("error happened because: ~p", [Reason]).   % With macro
14       logger:error("error happened because: ~p", [Reason]). % Without macro
15
16
17       To configure the Logger backend, use Kernel configuration parameters or
18       configuration functions in the Logger API.
19
20       By  default,  the Kernel application installs one log handler at system
21       start. This handler is named default. It receives and  processes  stan‐
22       dard  log events produced by the Erlang runtime system, standard behav‐
23       iours and different Erlang/OTP applications.  The  log  events  are  by
24       default printed to the terminal.
25
26       If you want your systems logs to be printed to a file instead, you must
27       configure the default handler to do so. The simplest way is to  include
28       the following in your sys.config:
29
30       [{kernel,
31         [{logger,
32           [{handler, default, logger_std_h,
33             #{config => #{file => "path/to/file.log"}}}]}]}].
34
35
36       For more information about:
37
38         * the Logger facility in general, see the User's Guide.
39
40         * how  to  configure  Logger,  see  the  Configuration section in the
41           User's Guide.
42
43         * the built-in handlers, see logger_std_h and logger_disk_log_h.
44
45         * the built-in formatter, see logger_formatter.
46
47         * built-in filters, see logger_filters.
48
49   Note:
50       Since Logger is new in Erlang/OTP 21.0, we  do  reserve  the  right  to
51       introduce  changes  to the Logger API and functionality in patches fol‐
52       lowing this release. These changes might or might not be backwards com‐
53       patible with the initial version.
54
55

DATA TYPES

57       filter() =
58           {fun((log_event(), filter_arg()) -> filter_return()),
59            filter_arg()}
60
61              A  filter  which  can  be installed as a handler filter, or as a
62              primary filter in Logger.
63
64       filter_arg() = term()
65
66              The second argument to the filter fun.
67
68       filter_id() = atom()
69
70              A unique identifier for a filter.
71
72       filter_return() = stop | ignore | log_event()
73
74              The return value from the filter fun.
75
76       formatter_config() = #{atom() => term()}
77
78              Configuration data for the  formatter.  See  logger_formatter(3)
79              for an example of a formatter implementation.
80
81       handler_config() =
82           #{id => handler_id(),
83             config => term(),
84             level => level() | all | none,
85             module => module(),
86             filter_default => log | stop,
87             filters => [{filter_id(), filter()}],
88             formatter => {module(), formatter_config()}}
89
90              Handler  configuration  data  for  Logger. The following default
91              values apply:
92
93                * level => all
94
95                * filter_default => log
96
97                * filters => []
98
99                * formatter => {logger_formatter, DefaultFormatterConfig}
100
101              In addition to these, the  following  fields  are  automatically
102              inserted  by  Logger, values taken from the two first parameters
103              to add_handler/3:
104
105                * id => HandlerId
106
107                * module => Module
108
109              These are read-only and cannot be changed in runtime.
110
111              Handler specific configuration data is inserted by  the  handler
112              callback  itself,  in  a sub structure associated with the field
113              named config. See the logger_std_h(3) and logger_disk_log_h man‐
114              ual  pages  for  information about the specifc configuration for
115              these handlers.
116
117              See the logger_formatter(3) manual page  for  information  about
118              the default configuration for this formatter.
119
120       handler_id() = atom()
121
122              A unique identifier for a handler instance.
123
124       level() =
125           emergency | alert | critical | error | warning | notice |
126           info | debug
127
128              The severity level for the message to be logged.
129
130       log_event() =
131           #{level := level(),
132             msg :=
133                 {io:format(), [term()]} |
134                 {report, report()} |
135                 {string, unicode:chardata()},
136             meta := metadata()}
137
138       metadata() =
139           #{pid => pid(),
140             gl => pid(),
141             time => timestamp(),
142             mfa => {module(), atom(), integer() >= 0},
143             file => file:filename(),
144             line => integer() >= 0,
145             domain => [atom()],
146             report_cb => report_cb(),
147             atom() => term()}
148
149              Metadata for the log event.
150
151              Logger adds the following metadata to each log event:
152
153                * pid => self()
154
155                * gl => group_leader()
156
157                * time => logger:timestamp()
158
159              When  a log macro is used, Logger also inserts location informa‐
160              tion:
161
162                * mfa => {?MODULE, ?FUNCTION_NAME, ?FUNCTION_ARITY}
163
164                * file => ?FILE
165
166                * line => ?LINE
167
168              You can add custom metadata, either by specifying a map  as  the
169              last parameter to any of the log macros or the API functions, or
170              by  setting  process  metadata  with  set_process_metadata/1  or
171              update_process_metadata/1.
172
173              Logger  merges  all  the metadata maps before forwarding the log
174              event to the handlers. If the same keys occur, values  from  the
175              log  call  overwrite  process  metadata, which in turn overwrite
176              values set by Logger.
177
178              The following custom metadata keys have special meaning:
179
180                domain:
181                  The value associated with this key is used  by  filters  for
182                  grouping  log events originating from, for example, specific
183                  functional areas. See logger_filters:domain/2 for a descrip‐
184                  tion of how this field can be used.
185
186                report_cb:
187                  If the log message is specified as a report(), the report_cb
188                  key can be associated with a fun (report callback) that con‐
189                  verts  the  report  to  a  format  string  and arguments, or
190                  directly  to  a  string.  See   the   type   definition   of
191                  report_cb(), and section Log Message in the User's Guide for
192                  more information about report callbacks.
193
194       msg_fun() =
195           fun((term()) ->
196                   {io:format(), [term()]} |
197                   report() |
198                   unicode:chardata())
199
200       olp_config() =
201           #{sync_mode_qlen => integer() >= 0,
202             drop_mode_qlen => integer() >= 1,
203             flush_qlen => integer() >= 1,
204             burst_limit_enable => boolean(),
205             burst_limit_max_count => integer() >= 1,
206             burst_limit_window_time => integer() >= 1,
207             overload_kill_enable => boolean(),
208             overload_kill_qlen => integer() >= 1,
209             overload_kill_mem_size => integer() >= 1,
210             overload_kill_restart_after => integer() >= 0 | infinity}
211
212       primary_config() =
213           #{level => level() | all | none,
214             filter_default => log | stop,
215             filters => [{filter_id(), filter()}]}
216
217              Primary configuration data for  Logger.  The  following  default
218              values apply:
219
220                * level => info
221
222                * filter_default => log
223
224                * filters => []
225
226       report() = map() | [{atom(), term()}]
227
228       report_cb() =
229           fun((report()) -> {io:format(), [term()]}) |
230           fun((report(), report_cb_config()) -> unicode:chardata())
231
232              A  fun  which  converts  a report() to a format string and argu‐
233              ments, or directly to a string. See section Log Message  in  the
234              User's Guide for more information.
235
236       report_cb_config() =
237           #{depth := integer() >= 1 | unlimited,
238             chars_limit := integer() >= 1 | unlimited,
239             single_line := boolean()}
240
241       timestamp() = integer()
242
243              A timestamp produced with logger:timestamp().
244

MACROS

246       The  following macros are defined in logger.hrl, which is included in a
247       module with the directive
248
249           -include_lib("kernel/include/logger.hrl").
250
251         * ?LOG_EMERGENCY(StringOrReport[,Metadata])
252
253         * ?LOG_EMERGENCY(FunOrFormat,Args[,Metadata])
254
255         * ?LOG_ALERT(StringOrReport[,Metadata])
256
257         * ?LOG_ALERT(FunOrFormat,Args[,Metadata])
258
259         * ?LOG_CRITICAL(StringOrReport[,Metadata])
260
261         * ?LOG_CRITICAL(FunOrFormat,Args[,Metadata])
262
263         * ?LOG_ERROR(StringOrReport[,Metadata])
264
265         * ?LOG_ERROR(FunOrFormat,Args[,Metadata])
266
267         * ?LOG_WARNING(StringOrReport[,Metadata])
268
269         * ?LOG_WARNING(FunOrFormat,Args[,Metadata])
270
271         * ?LOG_NOTICE(StringOrReport[,Metadata])
272
273         * ?LOG_NOTICE(FunOrFormat,Args[,Metadata])
274
275         * ?LOG_INFO(StringOrReport[,Metadata])
276
277         * ?LOG_INFO(FunOrFormat,Args[,Metadata])
278
279         * ?LOG_DEBUG(StringOrReport[,Metadata])
280
281         * ?LOG_DEBUG(FunOrFormat,Args[,Metadata])
282
283         * ?LOG(Level,StringOrReport[,Metadata])
284
285         * ?LOG(Level,FunOrFormat,Args[,Metadata])
286
287       All macros expand to a call to Logger, where Level is  taken  from  the
288       macro  name,  or from the first argument in the case of the ?LOG macro.
289       Location data is added to the metadata as  described  under  the  meta‐
290       data() type definition.
291
292       The  call  is wrapped in a case statement and will be evaluated only if
293       Level is equal to or below the configured log level.
294

LOGGING API FUNCTIONS

EXPORTS

297       emergency(StringOrReport[,Metadata])
298       emergency(Format,Args[,Metadata])
299       emergency(Fun,FunArgs[,Metadata])
300
301              Equivalent to log(emergency,...).
302
303       alert(StringOrReport[,Metadata])
304       alert(Format,Args[,Metadata])
305       alert(Fun,FunArgs[,Metadata])
306
307              Equivalent to log(alert,...).
308
309       critical(StringOrReport[,Metadata])
310       critical(Format,Args[,Metadata])
311       critical(Fun,FunArgs[,Metadata])
312
313              Equivalent to log(critical,...).
314
315       error(StringOrReport[,Metadata])
316       error(Format,Args[,Metadata])
317       error(Fun,FunArgs[,Metadata])
318
319              Equivalent to log(error,...).
320
321       warning(StringOrReport[,Metadata])
322       warning(Format,Args[,Metadata])
323       warning(Fun,FunArgs[,Metadata])
324
325              Equivalent to log(warning,...).
326
327       notice(StringOrReport[,Metadata])
328       notice(Format,Args[,Metadata])
329       notice(Fun,FunArgs[,Metadata])
330
331              Equivalent to log(notice,...).
332
333       info(StringOrReport[,Metadata])
334       info(Format,Args[,Metadata])
335       info(Fun,FunArgs[,Metadata])
336
337              Equivalent to log(info,...).
338
339       debug(StringOrReport[,Metadata])
340       debug(Format,Args[,Metadata])
341       debug(Fun,FunArgs[,Metadata])
342
343              Equivalent to log(debug,...).
344
345       log(Level, StringOrReport) -> ok
346
347       log(Level, StringOrReport, Metadata) -> ok
348
349       log(Level, Format, Args) -> ok
350
351       log(Level, Fun, FunArgs) -> ok
352
353       log(Level, Format, Args, Metadata) -> ok
354
355       log(Level, Fun, FunArgs, Metadata) -> ok
356
357              Types:
358
359                 Level = level()
360                 StringOrReport = unicode:chardata() | report()
361                 Format = io:format()
362                 Args = [term()]
363                 Fun = msg_fun()
364                 FunArgs = term()
365                 Metadata = metadata()
366
367              Log the given message.
368

CONFIGURATION API FUNCTIONS

EXPORTS

371       add_handler(HandlerId, Module, Config) -> ok | {error, term()}
372
373              Types:
374
375                 HandlerId = handler_id()
376                 Module = module()
377                 Config = handler_config()
378
379              Add a handler with the given configuration.
380
381              HandlerId is a unique identifier which must be used in all  sub‐
382              sequent calls referring to this handler.
383
384       add_handler_filter(HandlerId, FilterId, Filter) ->
385                             ok | {error, term()}
386
387              Types:
388
389                 HandlerId = handler_id()
390                 FilterId = filter_id()
391                 Filter = filter()
392
393              Add a filter to the specified handler.
394
395              The filter fun is called with the log event as the first parame‐
396              ter, and the specified filter_args() as the second parameter.
397
398              The return value of the fun specifies if a log event  is  to  be
399              discarded or forwarded to the handler callback:
400
401                log_event():
402                  The  filter  passed.  The  next  handler  filter, if any, is
403                  applied. If no more filters exist for this handler, the  log
404                  event is forwarded to the handler callback.
405
406                stop:
407                  The  filter  did  not pass, and the log event is immediately
408                  discarded.
409
410                ignore:
411                  The filter has no knowledge of the log event. The next  han‐
412                  dler  filter,  if  any, is applied. If no more filters exist
413                  for this handler, the value of the filter_default configura‐
414                  tion  parameter  for  the handler specifies if the log event
415                  shall be discarded or forwarded to the handler callback.
416
417              See section Filters in the User's  Guide  for  more  information
418              about filters.
419
420              Some  built-in  filters  exist. These are defined in logger_fil‐
421              ters.
422
423       add_handlers(Application) -> ok | {error, term()}
424
425              Types:
426
427                 Application = atom()
428
429              Reads the application configuration parameter logger  and  calls
430              add_handlers/1 with its contents.
431
432       add_handlers(HandlerConfig) -> ok | {error, term()}
433
434              Types:
435
436                 HandlerConfig = [config_handler()]
437                 config_handler() =
438                     {handler, handler_id(), module(), handler_config()}
439
440              This  function  should be used by custom Logger handlers to make
441              configuration consistent no  matter  which  handler  the  system
442              uses.  Normal  usage  is  to add a call to logger:add_handlers/1
443              just after the processes that the handler needs are started, and
444              pass the application's logger configuration as the argument. For
445              example:
446
447              -behaviour(application).
448              start(_, []) ->
449                  case supervisor:start_link({local, my_sup}, my_sup, []) of
450                      {ok, Pid} ->
451                          ok = logger:add_handlers(my_app),
452                          {ok, Pid, []};
453                      Error -> Error
454                   end.
455
456              This reads the logger configuration parameter  from  the  my_app
457              application  and starts the configured handlers. The contents of
458              the configuration use the same rules as the logger handler  con‐
459              figuration.
460
461              If the handler is meant to replace the default handler, the Ker‐
462              nel's default handler have to be disabled before the new handler
463              is added. A sys.config file that disables the Kernel handler and
464              adds a custom handler could look like this:
465
466              [{kernel,
467                [{logger,
468                  %% Disable the default Kernel handler
469                  [{handler, default, undefined}]}]},
470               {my_app,
471                [{logger,
472                  %% Enable this handler as the default
473                  [{handler, default, my_handler, #{}}]}]}].
474
475
476       add_primary_filter(FilterId, Filter) -> ok | {error, term()}
477
478              Types:
479
480                 FilterId = filter_id()
481                 Filter = filter()
482
483              Add a primary filter to Logger.
484
485              The filter fun is called with the log event as the first parame‐
486              ter, and the specified filter_args() as the second parameter.
487
488              The  return  value  of the fun specifies if a log event is to be
489              discarded or forwarded to the handlers:
490
491                log_event():
492                  The filter passed. The  next  primary  filter,  if  any,  is
493                  applied.  If no more primary filters exist, the log event is
494                  forwarded to the handler part of Logger, where handler  fil‐
495                  ters are applied.
496
497                stop:
498                  The  filter  did  not pass, and the log event is immediately
499                  discarded.
500
501                ignore:
502                  The filter has no knowledge of the log event. The next  pri‐
503                  mary  filter, if any, is applied. If no more primary filters
504                  exist, the value of the primary filter_default configuration
505                  parameter  specifies  if the log event shall be discarded or
506                  forwarded to the handler part.
507
508              See section  Filters in the User's Guide  for  more  information
509              about filters.
510
511              Some  built-in  filters  exist. These are defined in logger_fil‐
512              ters.
513
514       get_config() ->
515                     #{primary => primary_config(),
516                       handlers => [handler_config()],
517                       proxy => olp_config(),
518                       module_levels =>
519                           [{module(), level() | all | none}]}
520
521              Look up all current  Logger  configuration,  including  primary,
522              handler, and proxy configuration, and module level settings.
523
524       get_handler_config() -> [Config]
525
526              Types:
527
528                 Config = handler_config()
529
530              Look up the current configuration for all handlers.
531
532       get_handler_config(HandlerId) -> {ok, Config} | {error, term()}
533
534              Types:
535
536                 HandlerId = handler_id()
537                 Config = handler_config()
538
539              Look up the current configuration for the given handler.
540
541       get_handler_ids() -> [HandlerId]
542
543              Types:
544
545                 HandlerId = handler_id()
546
547              Look up the identities for all installed handlers.
548
549       get_primary_config() -> Config
550
551              Types:
552
553                 Config = primary_config()
554
555              Look up the current primary configuration for Logger.
556
557       get_proxy_config() -> Config
558
559              Types:
560
561                 Config = olp_config()
562
563              Look up the current configuration for the Logger proxy.
564
565              For  more  information about the proxy, see section Logger Proxy
566              in the Kernel User's Guide.
567
568       get_module_level() -> [{Module, Level}]
569
570              Types:
571
572                 Module = module()
573                 Level = level() | all | none
574
575              Look up all current module levels. Returns a list containing one
576              {Module,Level}  element  for  each  module  for which the module
577              level was previously set with set_module_level/2.
578
579       get_module_level(Modules) -> [{Module, Level}]
580
581              Types:
582
583                 Modules = [Module] | Module
584                 Module = module()
585                 Level = level() | all | none
586
587              Look up the current level for the given modules. Returns a  list
588              containing one {Module,Level} element for each of the given mod‐
589              ules for which the module level was previously set with set_mod‐
590              ule_level/2.
591
592       get_process_metadata() -> Meta | undefined
593
594              Types:
595
596                 Meta = metadata()
597
598              Retrieve     data    set    with    set_process_metadata/1    or
599              update_process_metadata/1.
600
601       i() -> ok
602
603       i(What) -> ok
604
605              Types:
606
607                 What = primary | handlers | proxy | modules | handler_id()
608
609              Pretty print the Logger configuration.
610
611       remove_handler(HandlerId) -> ok | {error, term()}
612
613              Types:
614
615                 HandlerId = handler_id()
616
617              Remove the handler identified by HandlerId.
618
619       remove_handler_filter(HandlerId, FilterId) -> ok | {error, term()}
620
621              Types:
622
623                 HandlerId = handler_id()
624                 FilterId = filter_id()
625
626              Remove the filter identified by FilterId from the handler  iden‐
627              tified by HandlerId.
628
629       remove_primary_filter(FilterId) -> ok | {error, term()}
630
631              Types:
632
633                 FilterId = filter_id()
634
635              Remove the primary filter identified by FilterId from Logger.
636
637       set_application_level(Application, Level) ->
638                                ok | {error, not_loaded}
639
640              Types:
641
642                 Application = atom()
643                 Level = level() | all | none
644
645              Set  the log level for all the modules of the specified applica‐
646              tion.
647
648              This  function  is  a  convenience  function  that  calls   log‐
649              ger:set_module_level/2 for each module associated with an appli‐
650              cation.
651
652       set_handler_config(HandlerId, Config) -> ok | {error, term()}
653
654              Types:
655
656                 HandlerId = handler_id()
657                 Config = handler_config()
658
659              Set configuration data for the  specified  handler.  This  over‐
660              writes the current handler configuration.
661
662              To  modify  the  existing configuration, use update_handler_con‐
663              fig/2, or, if a more complex merge is needed, read  the  current
664              configuration  with  get_handler_config/1,  then  do  the  merge
665              before writing the new configuration back with this function.
666
667              If a key is removed compared to the current  configuration,  and
668              the  key is known by Logger, the default value is used. If it is
669              a custom key, then it is up to the handler implementation if the
670              value is removed or a default value is inserted.
671
672       set_handler_config(HandlerId, Key :: level, Level) -> Return
673
674       set_handler_config(HandlerId,
675                          Key :: filter_default,
676                          FilterDefault) ->
677                             Return
678
679       set_handler_config(HandlerId, Key :: filters, Filters) -> Return
680
681       set_handler_config(HandlerId, Key :: formatter, Formatter) ->
682                             Return
683
684       set_handler_config(HandlerId, Key :: config, Config) -> Return
685
686              Types:
687
688                 HandlerId = handler_id()
689                 Level = level() | all | none
690                 FilterDefault = log | stop
691                 Filters = [{filter_id(), filter()}]
692                 Formatter = {module(), formatter_config()}
693                 Config = term()
694                 Return = ok | {error, term()}
695
696              Add  or  update configuration data for the specified handler. If
697              the given Key already  exists,  its  associated  value  will  be
698              changed  to  the  given  value. If it does not exist, it will be
699              added.
700
701              If the value is incomplete, which for example can  be  the  case
702              for  the  config key, it is up to the handler implementation how
703              the unspecified parts are set. For all handlers  in  the  Kernel
704              application,  unspecified  data  for  the  config  key is set to
705              default values. To update only  specified  data,  and  keep  the
706              existing  configuration  for  the  rest, use update_handler_con‐
707              fig/3.
708
709              See the definition of the handler_config() type for more  infor‐
710              mation about the different parameters.
711
712       set_primary_config(Config) -> ok | {error, term()}
713
714              Types:
715
716                 Config = primary_config()
717
718              Set  primary  configuration data for Logger. This overwrites the
719              current configuration.
720
721              To modify the existing  configuration,  use  update_primary_con‐
722              fig/1,  or,  if a more complex merge is needed, read the current
723              configuration  with  get_primary_config/0,  then  do  the  merge
724              before writing the new configuration back with this function.
725
726              If  a  key is removed compared to the current configuration, the
727              default value is used.
728
729       set_primary_config(Key :: level, Level) -> ok | {error, term()}
730
731       set_primary_config(Key :: filter_default, FilterDefault) ->
732                             ok | {error, term()}
733
734       set_primary_config(Key :: filters, Filters) ->
735                             ok | {error, term()}
736
737              Types:
738
739                 Level = level() | all | none
740                 FilterDefault = log | stop
741                 Filters = [{filter_id(), filter()}]
742
743              Add or update primary configuration  data  for  Logger.  If  the
744              given  Key  already exists, its associated value will be changed
745              to the given value. If it does not exist, it will be added.
746
747       set_proxy_config(Config) -> ok | {error, term()}
748
749              Types:
750
751                 Config = olp_config()
752
753              Set configuration data for the Logger proxy. This overwrites the
754              current  proxy configuration. Keys that are not specified in the
755              Config map gets default values.
756
757              To modify the existing configuration, use update_proxy_config/1,
758              or, if a more complex merge is needed, read the current configu‐
759              ration with get_proxy_config/0, then do the merge before writing
760              the new configuration back with this function.
761
762              For  more  information about the proxy, see section Logger Proxy
763              in the Kernel User's Guide.
764
765       set_module_level(Modules, Level) -> ok | {error, term()}
766
767              Types:
768
769                 Modules = [module()] | module()
770                 Level = level() | all | none
771
772              Set the log level for the specified modules.
773
774              The log level for a module overrides the primary  log  level  of
775              Logger  for  log events originating from the module in question.
776              Notice, however, that it does not override the level  configura‐
777              tion for any handler.
778
779              For  example:  Assume  that  the primary log level for Logger is
780              info, and there is one handler, h1, with level info and one han‐
781              dler, h2, with level debug.
782
783              With this configuration, no debug messages will be logged, since
784              they are all stopped by the primary log level.
785
786              If the level for mymodule is now set to debug, then debug events
787              from  this  module  will be logged by the handler h2, but not by
788              handler h1.
789
790              Debug events from other modules are still not logged.
791
792              To change the primary log level for Logger, use set_primary_con‐
793              fig(level, Level).
794
795              To  change  the  log  level  for a handler, use set_handler_con‐
796              fig(HandlerId, level, Level).
797
798          Note:
799              The originating module for a log event is only detected  if  the
800              key  mfa exists in the metadata, and is associated with {Module,
801              Function, Arity}. When log macros are used, this association  is
802              automatically  added  to  all  log events. If an API function is
803              called directly, without using a macro, the logging client  must
804              explicitly  add this information if module levels shall have any
805              effect.
806
807
808       set_process_metadata(Meta) -> ok
809
810              Types:
811
812                 Meta = metadata()
813
814              Set metadata which Logger shall automatically insert in all  log
815              events produced on the current process.
816
817              Location  data produced by the log macros, and/or metadata given
818              as argument to the log call (API function or macro), are  merged
819              with  the  process metadata. If the same keys occur, values from
820              the metadata argument to the log call overwrite values from  the
821              process  metadata, which in turn overwrite values from the loca‐
822              tion data.
823
824              Subsequent calls to this function overwrites previous data  set.
825              To   update   existing  data  instead  of  overwriting  it,  see
826              update_process_metadata/1.
827
828       unset_application_level(Application) -> ok | {error, not_loaded}
829
830              Types:
831
832                 Application = atom()
833
834              Unset the log level for all the modules of the specified  appli‐
835              cation.
836
837              This   function  is  a  convinience  function  that  calls  log‐
838              ger:unset_module_level/2 for  each  module  associated  with  an
839              application.
840
841       unset_module_level() -> ok
842
843              Remove module specific log settings. After this, the primary log
844              level is used for all modules.
845
846       unset_module_level(Modules) -> ok
847
848              Types:
849
850                 Modules = [module()] | module()
851
852              Remove module specific log settings. After this, the primary log
853              level is used for the specified modules.
854
855       unset_process_metadata() -> ok
856
857              Delete     data     set     with    set_process_metadata/1    or
858              update_process_metadata/1.
859
860       update_formatter_config(HandlerId, FormatterConfig) ->
861                                  ok | {error, term()}
862
863              Types:
864
865                 HandlerId = handler_id()
866                 FormatterConfig = formatter_config()
867
868              Update the formatter configuration for the specified handler.
869
870              The new configuration is merged with the existing formatter con‐
871              figuration.
872
873              To overwrite the existing configuration without any merge, use
874
875              set_handler_config(HandlerId, formatter, {FormatterModule, FormatterConfig}).
876
877       update_formatter_config(HandlerId, Key, Value) ->
878                                  ok | {error, term()}
879
880              Types:
881
882                 HandlerId = handler_id()
883                 Key = atom()
884                 Value = term()
885
886              Update the formatter configuration for the specified handler.
887
888              This is equivalent to
889
890              update_formatter_config(HandlerId, #{Key => Value})
891
892       update_handler_config(HandlerId, Config) -> ok | {error, term()}
893
894              Types:
895
896                 HandlerId = handler_id()
897                 Config = handler_config()
898
899              Update  configuration data for the specified handler. This func‐
900              tion behaves as if it was implemented as follows:
901
902              {ok, {_, Old}} = logger:get_handler_config(HandlerId),
903              logger:set_handler_config(HandlerId, maps:merge(Old, Config)).
904
905
906              To overwrite the existing configuration without any  merge,  use
907              set_handler_config/2.
908
909       update_handler_config(HandlerId, Key :: level, Level) -> Return
910
911       update_handler_config(HandlerId,
912                             Key :: filter_default,
913                             FilterDefault) ->
914                                Return
915
916       update_handler_config(HandlerId, Key :: filters, Filters) ->
917                                Return
918
919       update_handler_config(HandlerId, Key :: formatter, Formatter) ->
920                                Return
921
922       update_handler_config(HandlerId, Key :: config, Config) -> Return
923
924              Types:
925
926                 HandlerId = handler_id()
927                 Level = level() | all | none
928                 FilterDefault = log | stop
929                 Filters = [{filter_id(), filter()}]
930                 Formatter = {module(), formatter_config()}
931                 Config = term()
932                 Return = ok | {error, term()}
933
934              Add  or  update configuration data for the specified handler. If
935              the given Key already  exists,  its  associated  value  will  be
936              changed  to  the  given  value. If it does not exist, it will be
937              added.
938
939              If the value is incomplete, which for example can  be  the  case
940              for  the  config key, it is up to the handler implementation how
941              the unspecified parts are set. For all handlers  in  the  Kernel
942              application, unspecified data for the config key is not changed.
943              To reset  unspecified  data  to  default  values,  use  set_han‐
944              dler_config/3.
945
946              See  the definition of the handler_config() type for more infor‐
947              mation about the different parameters.
948
949       update_primary_config(Config) -> ok | {error, term()}
950
951              Types:
952
953                 Config = primary_config()
954
955              Update primary configuration  data  for  Logger.  This  function
956              behaves as if it was implemented as follows:
957
958              Old = logger:get_primary_config(),
959              logger:set_primary_config(maps:merge(Old, Config)).
960
961
962              To  overwrite  the existing configuration without any merge, use
963              set_primary_config/1.
964
965       update_process_metadata(Meta) -> ok
966
967              Types:
968
969                 Meta = metadata()
970
971              Set or update metadata to use when logging from current process
972
973              If process metadata exists for the current process,  this  func‐
974              tion behaves as if it was implemented as follows:
975
976              logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
977
978
979              If   no   process  metadata  exists,  the  function  behaves  as
980              set_process_metadata/1.
981
982       update_proxy_config(Config) -> ok | {error, term()}
983
984              Types:
985
986                 Config = olp_config()
987
988              Update configuration data for the Logger  proxy.  This  function
989              behaves as if it was implemented as follows:
990
991              Old = logger:get_proxy_config(),
992              logger:set_proxy_config(maps:merge(Old, Config)).
993
994
995              To  overwrite  the existing configuration without any merge, use
996              set_proxy_config/1.
997
998              For more information about the proxy, see section  Logger  Proxy
999              in the Kernel User's Guide.
1000

MISCELLANEOUS API FUNCTIONS

EXPORTS

1003       compare_levels(Level1, Level2) -> eq | gt | lt
1004
1005              Types:
1006
1007                 Level1 = Level2 = level() | all | none
1008
1009              Compare  the severity of two log levels. Returns gt if Level1 is
1010              more severe than Level2, lt if Level1 is less severe, and eq  if
1011              the levels are equal.
1012
1013       format_report(Report) -> FormatArgs
1014
1015              Types:
1016
1017                 Report = report()
1018                 FormatArgs = {io:format(), [term()]}
1019
1020              Convert  a log message on report form to {Format, Args}. This is
1021              the default report callback used  by  logger_formatter  when  no
1022              custom  report callback is found. See section Log Message in the
1023              Kernel User's Guide for information about report  callbacks  and
1024              valid forms of log messages.
1025
1026              The  function produces lines of Key: Value from key-value lists.
1027              Strings are printed with ~ts and other terms with ~tp.
1028
1029              If Report is a map, it is converted to a key-value  list  before
1030              formatting as such.
1031
1032       timestamp() -> timestamp()
1033
1034              Return a timestamp that can be inserted as the time field in the
1035              meta  data  for  a  log  event.  It  is  produced  with  os:sys‐
1036              tem_time(microsecond).
1037
1038              Notice that Logger automatically inserts a timestamp in the meta
1039              data unless it already exists. This function is exported for the
1040              rare  case when the timestamp must be taken at a different point
1041              in time than when the log event is issued.
1042

HANDLER CALLBACK FUNCTIONS

1044       The following functions are to be exported from a handler callback mod‐
1045       ule.
1046

EXPORTS

1048       HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason}
1049
1050              Types:
1051
1052                 Config1 = Config2 = handler_config()
1053                 Reason = term()
1054
1055              This callback function is optional.
1056
1057              The  function  is called on a temporary process when an new han‐
1058              dler is about to be added. The purpose is to verify the configu‐
1059              ration and initiate all resources needed by the handler.
1060
1061              The handler identity is associated with the id key in Config1.
1062
1063              If  everything  succeeds, the callback function can add possible
1064              default values or internal state values  to  the  configuration,
1065              and return the adjusted map in {ok,Config2}.
1066
1067              If  the configuration is faulty, or if the initiation fails, the
1068              callback function must return {error,Reason}.
1069
1070       HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Con‐
1071       fig} | {error, Reason}
1072
1073              Types:
1074
1075                 SetOrUpdate = set | update
1076                 OldConfig = NewConfig = Config = handler_config()
1077                 Reason = term()
1078
1079              This callback function is optional.
1080
1081              The  function is called on a temporary process when the configu‐
1082              ration for a handler is about to change. The purpose is to  ver‐
1083              ify and act on the new configuration.
1084
1085              OldConfig is the existing configuration and NewConfig is the new
1086              configuration.
1087
1088              The handler identity is associated with the id key in OldConfig.
1089
1090              SetOrUpdate has the value set if the configuration change origi‐
1091              nates  from  a  call to set_handler_config/2,3, and update if it
1092              originates from update_handler_config/2,3. The handler  can  use
1093              this parameteter to decide how to update the value of the config
1094              field, that is, the handler specific configuration  data.  Typi‐
1095              cally,  if SetOrUpdate equals set, values that are not specified
1096              must be  given  their  default  values.  If  SetOrUpdate  equals
1097              update, the values found in OldConfig must be used instead.
1098
1099              If everything succeeds, the callback function must return a pos‐
1100              sibly adjusted configuration in {ok,Config}.
1101
1102              If the configuration  is  faulty,  the  callback  function  must
1103              return {error,Reason}.
1104
1105       HModule:filter_config(Config) -> FilteredConfig
1106
1107              Types:
1108
1109                 Config = FilteredConfig = handler_config()
1110
1111              This callback function is optional.
1112
1113              The  function is called when one of the Logger API functions for
1114              fetching the handler configuration is called, for  example  log‐
1115              ger:get_handler_config/1.
1116
1117              It  allows  the  handler to remove internal data fields from its
1118              configuration data before it is returned to the caller.
1119
1120       HModule:log(LogEvent, Config) -> void()
1121
1122              Types:
1123
1124                 LogEvent = log_event()
1125                 Config = handler_config()
1126
1127              This callback function is mandatory.
1128
1129              The function is called when all primary filters and all  handler
1130              filters  for  the  handler in question have passed for the given
1131              log event. It is called on the  client  process,  that  is,  the
1132              process that issued the log event.
1133
1134              The handler identity is associated with the id key in Config.
1135
1136              The handler must log the event.
1137
1138              The return value from this function is ignored by Logger.
1139
1140       HModule:removing_handler(Config) -> ok
1141
1142              Types:
1143
1144                 Config = handler_config()
1145
1146              This callback function is optional.
1147
1148              The  function is called on a temporary process when a handler is
1149              about to be removed. The purpose is  to  release  all  resources
1150              used by the handler.
1151
1152              The handler identity is associated with the id key in Config.
1153
1154              The return value is ignored by Logger.
1155

FORMATTER CALLBACK FUNCTIONS

1157       The  following  functions  are to be exported from a formatter callback
1158       module.
1159

EXPORTS

1161       FModule:check_config(FConfig) -> ok | {error, Reason}
1162
1163              Types:
1164
1165                 FConfig = formatter_config()
1166                 Reason = term()
1167
1168              This callback function is optional.
1169
1170              The function is called by a Logger when formatter  configuration
1171              is  set  or modified. The formatter must validate the given con‐
1172              figuration and return ok if it is correct, and {error,Reason} if
1173              it is faulty.
1174
1175              The following Logger API functions can trigger this callback:
1176
1177                * logger:add_handler/3
1178
1179                * logger:set_handler_config/2,3
1180
1181                * logger:update_handler_config/2,3
1182
1183                * logger:update_formatter_config/2
1184
1185              See  logger_formatter(3)  for  an  example  implementation. log‐
1186              ger_formatter is the default formatter used by Logger.
1187
1188       FModule:format(LogEvent, FConfig) -> FormattedLogEntry
1189
1190              Types:
1191
1192                 LogEvent = log_event()
1193                 FConfig = formatter_config()
1194                 FormattedLogEntry = unicode:chardata()
1195
1196              This callback function is mandatory.
1197
1198              The function can be called by a log handler  to  convert  a  log
1199              event  term  to  a printable string. The returned value can, for
1200              example, be printed as a log entry to  the  console  or  a  file
1201              using io:put_chars/1,2.
1202
1203              See  logger_formatter(3)  for  an  example  implementation. log‐
1204              ger_formatter is the default formatter used by Logger.
1205

SEE ALSO

1207       config(4), erlang(3), io(3),  logger_disk_log_h(3),  logger_filters(3),
1208       logger_formatter(3), logger_std_h(3), unicode(3)
1209
1210
1211
1212Ericsson AB                       kernel 6.5                         logger(3)
Impressum