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  de‐
24       fault 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  in‐
51       troduce  changes to the Logger API and functionality in patches follow‐
52       ing this release. These changes might or might not be backwards compat‐
53       ible 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 in‐
102              serted  by Logger, values taken from the two first parameters to
103              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(3)
114              manual  pages  for  information about the specific configuration
115              for 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:
169
170                * specifying a map as the last parameter to  any  of  the  log
171                  macros or the logger API functions.
172
173                * setting  process metadata with set_process_metadata/1 or up‐
174                  date_process_metadata/1.
175
176                * setting  primary  metadata  with   set_primary_config/1   or
177                  through the kernel configuration parameter  logger_metadata
178
179          Note:
180              When  adding  custom  metadata,  make sure not to use any of the
181              keys mentioned above as that may cause a lot of confusion  about
182              the log events.
183
184
185              Logger  merges  all  the metadata maps before forwarding the log
186              event to the handlers. If the same keys occur, values  from  the
187              log  call  overwrite process metadata, which overwrites the pri‐
188              mary metadata, which in turn overwrite values set by Logger.
189
190              The following custom metadata keys have special meaning:
191
192                domain:
193                  The value associated with this key is used  by  filters  for
194                  grouping  log events originating from, for example, specific
195                  functional areas. See logger_filters:domain/2 for a descrip‐
196                  tion of how this field can be used.
197
198                report_cb:
199                  If the log message is specified as a report(), the report_cb
200                  key can be associated with a fun (report callback) that con‐
201                  verts  the  report  to a format string and arguments, or di‐
202                  rectly to a string. See the type definition of  report_cb(),
203                  and  section Log Message in the User's Guide for more infor‐
204                  mation about report callbacks.
205
206       msg_fun() =
207           fun((term()) ->
208                   msg_fun_return() | {msg_fun_return(), metadata()})
209
210       msg_fun_return() =
211           {io:format(), [term()]} |
212           report() |
213           unicode:chardata() |
214           ignore
215
216       olp_config() =
217           #{sync_mode_qlen => integer() >= 0,
218             drop_mode_qlen => integer() >= 1,
219             flush_qlen => integer() >= 1,
220             burst_limit_enable => boolean(),
221             burst_limit_max_count => integer() >= 1,
222             burst_limit_window_time => integer() >= 1,
223             overload_kill_enable => boolean(),
224             overload_kill_qlen => integer() >= 1,
225             overload_kill_mem_size => integer() >= 1,
226             overload_kill_restart_after => integer() >= 0 | infinity}
227
228       primary_config() =
229           #{level => level() | all | none,
230             metadata => metadata(),
231             filter_default => log | stop,
232             filters => [{filter_id(), filter()}]}
233
234              Primary configuration data for  Logger.  The  following  default
235              values apply:
236
237                * level => info
238
239                * filter_default => log
240
241                * filters => []
242
243       report() = map() | [{atom(), term()}]
244
245       report_cb() =
246           fun((report()) -> {io:format(), [term()]}) |
247           fun((report(), report_cb_config()) -> unicode:chardata())
248
249              A  fun  which  converts  a report() to a format string and argu‐
250              ments, or directly to a string. See section Log Message  in  the
251              User's Guide for more information.
252
253       report_cb_config() =
254           #{depth := integer() >= 1 | unlimited,
255             chars_limit := integer() >= 1 | unlimited,
256             single_line := boolean()}
257
258       timestamp() = integer()
259
260              A timestamp produced with logger:timestamp().
261

MACROS

263       The  following macros are defined in logger.hrl, which is included in a
264       module with the directive
265
266           -include_lib("kernel/include/logger.hrl").
267
268         * ?LOG_EMERGENCY(StringOrReport[,Metadata])
269
270         * ?LOG_EMERGENCY(FunOrFormat,Args[,Metadata])
271
272         * ?LOG_ALERT(StringOrReport[,Metadata])
273
274         * ?LOG_ALERT(FunOrFormat,Args[,Metadata])
275
276         * ?LOG_CRITICAL(StringOrReport[,Metadata])
277
278         * ?LOG_CRITICAL(FunOrFormat,Args[,Metadata])
279
280         * ?LOG_ERROR(StringOrReport[,Metadata])
281
282         * ?LOG_ERROR(FunOrFormat,Args[,Metadata])
283
284         * ?LOG_WARNING(StringOrReport[,Metadata])
285
286         * ?LOG_WARNING(FunOrFormat,Args[,Metadata])
287
288         * ?LOG_NOTICE(StringOrReport[,Metadata])
289
290         * ?LOG_NOTICE(FunOrFormat,Args[,Metadata])
291
292         * ?LOG_INFO(StringOrReport[,Metadata])
293
294         * ?LOG_INFO(FunOrFormat,Args[,Metadata])
295
296         * ?LOG_DEBUG(StringOrReport[,Metadata])
297
298         * ?LOG_DEBUG(FunOrFormat,Args[,Metadata])
299
300         * ?LOG(Level,StringOrReport[,Metadata])
301
302         * ?LOG(Level,FunOrFormat,Args[,Metadata])
303
304       All macros expand to a call to Logger, where Level is  taken  from  the
305       macro  name,  or from the first argument in the case of the ?LOG macro.
306       Location data is added to the metadata as  described  under  the  meta‐
307       data() type definition.
308
309       The  call  is wrapped in a case statement and will be evaluated only if
310       Level is equal to or below the configured log level.
311

LOGGING API FUNCTIONS

EXPORTS

314       emergency(StringOrReport[,Metadata])
315       emergency(Format,Args[,Metadata])
316       emergency(Fun,FunArgs[,Metadata])
317
318              Equivalent to log(emergency,...).
319
320       alert(StringOrReport[,Metadata])
321       alert(Format,Args[,Metadata])
322       alert(Fun,FunArgs[,Metadata])
323
324              Equivalent to log(alert,...).
325
326       critical(StringOrReport[,Metadata])
327       critical(Format,Args[,Metadata])
328       critical(Fun,FunArgs[,Metadata])
329
330              Equivalent to log(critical,...).
331
332       error(StringOrReport[,Metadata])
333       error(Format,Args[,Metadata])
334       error(Fun,FunArgs[,Metadata])
335
336              Equivalent to log(error,...).
337
338       warning(StringOrReport[,Metadata])
339       warning(Format,Args[,Metadata])
340       warning(Fun,FunArgs[,Metadata])
341
342              Equivalent to log(warning,...).
343
344       notice(StringOrReport[,Metadata])
345       notice(Format,Args[,Metadata])
346       notice(Fun,FunArgs[,Metadata])
347
348              Equivalent to log(notice,...).
349
350       info(StringOrReport[,Metadata])
351       info(Format,Args[,Metadata])
352       info(Fun,FunArgs[,Metadata])
353
354              Equivalent to log(info,...).
355
356       debug(StringOrReport[,Metadata])
357       debug(Format,Args[,Metadata])
358       debug(Fun,FunArgs[,Metadata])
359
360              Equivalent to log(debug,...).
361
362       log(Level, StringOrReport) -> ok
363
364       log(Level, StringOrReport, Metadata) -> ok
365
366       log(Level, Format, Args) -> ok
367
368       log(Level, Fun, FunArgs) -> ok
369
370       log(Level, Format, Args, Metadata) -> ok
371
372       log(Level, Fun, FunArgs, Metadata) -> ok
373
374              Types:
375
376                 Level = level()
377                 StringOrReport = unicode:chardata() | report()
378                 Format = io:format()
379                 Args = [term()]
380                 Fun = msg_fun()
381                 FunArgs = term()
382                 Metadata = metadata()
383
384              Create a log event at the given log level, with the  given  mes‐
385              sage to be logged and metadata. Examples:
386
387              %% A plain string
388              logger:log(info, "Hello World").
389              %% A plain string with metadata
390              logger:log(debug, "Hello World", #{ meta => data }).
391              %% A format string with arguments
392              logger:log(warning, "The roof is on ~ts",[Cause]).
393              %% A report
394              logger:log(warning, #{ what => roof, cause => Cause }).
395
396
397              The message and metadata can either be given directly in the ar‐
398              guments, or returned from a fun. Passing a fun  instead  of  the
399              message/metadata  directly  is useful in scenarios when the mes‐
400              sage/metadata is very expensive to compute. This is because  the
401              fun  is  only  evaluted  when  the  message/metadata is actually
402              needed, which may be not at all if the log event is  not  to  be
403              logged. Examples:
404
405              %% A plain string with expensive metadata
406              logger:info(fun([]) -> {"Hello World", #{ meta => expensive() }} end,[]).
407              %% An expensive report
408              logger:debug(fun(What) -> #{ what => What, cause => expensive() } end,roof).
409              %% A plain string with expensive metadata and normal metadata
410              logger:debug(fun([]) -> {"Hello World", #{ meta => expensive() }} end,[],
411                           #{ meta => data }).
412
413
414              When metadata is given both as an argument and returned from the
415              fun they are merged. If equal keys exists the values  are  taken
416              from the metadata returned by the fun.
417

CONFIGURATION API FUNCTIONS

EXPORTS

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

MISCELLANEOUS API FUNCTIONS

EXPORTS

1054       compare_levels(Level1, Level2) -> eq | gt | lt
1055
1056              Types:
1057
1058                 Level1 = Level2 = level() | all | none
1059
1060              Compare the severity of two log levels. Returns gt if Level1  is
1061              more  severe than Level2, lt if Level1 is less severe, and eq if
1062              the levels are equal.
1063
1064       format_report(Report) -> FormatArgs
1065
1066              Types:
1067
1068                 Report = report()
1069                 FormatArgs = {io:format(), [term()]}
1070
1071              Convert a log message on report form to {Format, Args}. This  is
1072              the  default report callback used by logger_formatter(3) when no
1073              custom report callback is found. See section Log Message in  the
1074              Kernel  User's  Guide for information about report callbacks and
1075              valid forms of log messages.
1076
1077              The function produces lines of Key: Value from key-value  lists.
1078              Strings are printed with ~ts and other terms with ~tp.
1079
1080              If  Report  is a map, it is converted to a key-value list before
1081              formatting as such.
1082
1083       timestamp() -> timestamp()
1084
1085              Return a timestamp that can be inserted as the time field in the
1086              meta  data  for  a  log  event.  It  is  produced  with  os:sys‐
1087              tem_time(microsecond).
1088
1089              Notice that Logger automatically inserts a timestamp in the meta
1090              data unless it already exists. This function is exported for the
1091              rare case when the timestamp must be taken at a different  point
1092              in time than when the log event is issued.
1093
1094       reconfigure() -> ok | {error, term()}
1095
1096              Reconfigure  Logger  using updated kernel configuration that was
1097              set after kernel application was loaded.
1098
1099              Beware, that this is meant to be run only by  the  build  tools,
1100              not  manually  during  application  lifetime,  as this may cause
1101              missing log entries.
1102

HANDLER CALLBACK FUNCTIONS

1104       The following functions are to be exported from a handler callback mod‐
1105       ule.
1106

EXPORTS

1108       HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason}
1109
1110              Types:
1111
1112                 Config1 = Config2 = handler_config()
1113                 Reason = term()
1114
1115              This callback function is optional.
1116
1117              The function is called on a temporary process when a new handler
1118              is about to be added. The purpose is to verify the configuration
1119              and initiate all resources needed by the handler.
1120
1121              The handler identity is associated with the id key in Config1.
1122
1123              If  everything  succeeds, the callback function can add possible
1124              default values or internal state values  to  the  configuration,
1125              and return the adjusted map in {ok,Config2}.
1126
1127              If  the configuration is faulty, or if the initiation fails, the
1128              callback function must return {error,Reason}.
1129
1130       HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Con‐
1131       fig} | {error, Reason}
1132
1133              Types:
1134
1135                 SetOrUpdate = set | update
1136                 OldConfig = NewConfig = Config = handler_config()
1137                 Reason = term()
1138
1139              This callback function is optional.
1140
1141              The  function is called on a temporary process when the configu‐
1142              ration for a handler is about to change. The purpose is to  ver‐
1143              ify and act on the new configuration.
1144
1145              OldConfig is the existing configuration and NewConfig is the new
1146              configuration.
1147
1148              The handler identity is associated with the id key in OldConfig.
1149
1150              SetOrUpdate has the value set if the configuration change origi‐
1151              nates  from  a  call to set_handler_config/2,3, and update if it
1152              originates from update_handler_config/2,3. The handler  can  use
1153              this  parameter  to decide how to update the value of the config
1154              field, that is, the handler specific configuration  data.  Typi‐
1155              cally,  if SetOrUpdate equals set, values that are not specified
1156              must be given their default values. If  SetOrUpdate  equals  up‐
1157              date, the values found in OldConfig must be used instead.
1158
1159              If everything succeeds, the callback function must return a pos‐
1160              sibly adjusted configuration in {ok,Config}.
1161
1162              If the configuration is faulty, the callback function  must  re‐
1163              turn {error,Reason}.
1164
1165       HModule:filter_config(Config) -> FilteredConfig
1166
1167              Types:
1168
1169                 Config = FilteredConfig = handler_config()
1170
1171              This callback function is optional.
1172
1173              The  function is called when one of the Logger API functions for
1174              fetching the handler configuration is called, for  example  log‐
1175              ger:get_handler_config/1.
1176
1177              It  allows  the  handler to remove internal data fields from its
1178              configuration data before it is returned to the caller.
1179
1180       HModule:log(LogEvent, Config) -> void()
1181
1182              Types:
1183
1184                 LogEvent = log_event()
1185                 Config = handler_config()
1186
1187              This callback function is mandatory.
1188
1189              The function is called when all primary filters and all  handler
1190              filters  for  the  handler in question have passed for the given
1191              log event. It is called on the  client  process,  that  is,  the
1192              process that issued the log event.
1193
1194              The handler identity is associated with the id key in Config.
1195
1196              The handler must log the event.
1197
1198              The return value from this function is ignored by Logger.
1199
1200       HModule:removing_handler(Config) -> ok
1201
1202              Types:
1203
1204                 Config = handler_config()
1205
1206              This callback function is optional.
1207
1208              The  function is called on a temporary process when a handler is
1209              about to be removed. The purpose is  to  release  all  resources
1210              used by the handler.
1211
1212              The handler identity is associated with the id key in Config.
1213
1214              The return value is ignored by Logger.
1215

FORMATTER CALLBACK FUNCTIONS

1217       The  following  functions  are to be exported from a formatter callback
1218       module.
1219

EXPORTS

1221       FModule:check_config(FConfig) -> ok | {error, Reason}
1222
1223              Types:
1224
1225                 FConfig = formatter_config()
1226                 Reason = term()
1227
1228              This callback function is optional.
1229
1230              The function is called by a Logger when formatter  configuration
1231              is  set  or modified. The formatter must validate the given con‐
1232              figuration and return ok if it is correct, and {error,Reason} if
1233              it is faulty.
1234
1235              The following Logger API functions can trigger this callback:
1236
1237                * logger:add_handler/3
1238
1239                * logger:set_handler_config/2,3
1240
1241                * logger:update_handler_config/2,3
1242
1243                * logger:update_formatter_config/2
1244
1245              See  logger_formatter(3)  for  an  example  implementation. log‐
1246              ger_formatter is the default formatter used by Logger.
1247
1248       FModule:format(LogEvent, FConfig) -> FormattedLogEntry
1249
1250              Types:
1251
1252                 LogEvent = log_event()
1253                 FConfig = formatter_config()
1254                 FormattedLogEntry = unicode:chardata()
1255
1256              This callback function is mandatory.
1257
1258              The function can be called by a log handler  to  convert  a  log
1259              event  term  to  a printable string. The returned value can, for
1260              example, be printed as a log entry to the console or a file  us‐
1261              ing io:put_chars/1,2.
1262
1263              See  logger_formatter(3)  for  an  example  implementation. log‐
1264              ger_formatter is the default formatter used by Logger.
1265

SEE ALSO

1267       config(4), erlang(3), io(3),  logger_disk_log_h(3),  logger_filters(3),
1268       logger_formatter(3), logger_std_h(3), unicode(3)
1269
1270
1271
1272Ericsson AB                      kernel 8.3.2                        logger(3)
Impressum