1logger(3) Erlang Module Definition logger(3)
2
6 logger - API module for Logger, the standard logging facility
7 in Erlang/OTP.
8
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 ?LOG_ERROR("error happened because: ~p", [Reason]). % With macro
14 logger:error("error happened because: ~p", [Reason]). % Without macro
15 To configure the Logger backend, use Kernel configuration parameters or
18 configuration functions in the Logger API.
19 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 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 [{kernel,
31 [{logger,
32 [{handler, default, logger_std_h,
33 #{config => #{file => "path/to/file.log"}}}]}]}].
34 For more information about:
37 * the Logger facility in general, see the User's Guide.
39 * how to configure Logger, see the Configuration section in the
41 User's Guide.
42 * the built-in handlers, see logger_std_h and logger_disk_log_h.
44 * the built-in formatter, see logger_formatter.
46 * built-in filters, see logger_filters.
48 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
57 filter() =
58 {fun((log_event(), filter_arg()) -> filter_return()),
59 filter_arg()}
60 A filter which can be installed as a handler filter, or as a
62 primary filter in Logger.
63 filter_arg() = term()
65 The second argument to the filter fun.
67 filter_id() = atom()
69 A unique identifier for a filter.
71 filter_return() = stop | ignore | log_event()
73 The return value from the filter fun.
75 formatter_config() = #{atom() => term()}
77 Configuration data for the formatter. See logger_formatter(3)
79 for an example of a formatter implementation.
80 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 Handler configuration data for Logger. The following default
91 values apply:
92 * level => all
94 * filter_default => log
96 * filters => []
98 * formatter => {logger_formatter, DefaultFormatterConfig}
100 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 * id => HandlerId
106 * module => Module
108 These are read-only and cannot be changed in runtime.
110 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 See the logger_formatter(3) manual page for information about
118 the default configuration for this formatter.
119 handler_id() = atom()
121 A unique identifier for a handler instance.
123 level() =
125 emergency |
126 alert |
127 critical |
128 error |
129 warning |
130 notice |
131 info |
132 debug
133 The severity level for the message to be logged.
135 log_event() =
137 #{level := level(),
138 msg :=
139 {io:format(), [term()]} |
140 {report, report()} |
141 {string, unicode:chardata()},
142 meta := metadata()}
143 metadata() =
145 #{pid => pid(),
146 gl => pid(),
147 time => timestamp(),
148 mfa => {module(), atom(), integer() >= 0},
149 file => file:filename(),
150 line => integer() >= 0,
151 domain => [atom()],
152 report_cb => report_cb(),
153 atom() => term()}
154 Metadata for the log event.
156 Logger adds the following metadata to each log event:
158 * pid => self()
160 * gl => group_leader()
162 * time => logger:timestamp()
164 When a log macro is used, Logger also inserts location informa‐
166 tion:
167 * mfa => {?MODULE, ?FUNCTION_NAME, ?FUNCTION_ARITY}
169 * file => ?FILE
171 * line => ?LINE
173 You can add custom metadata, either by specifying a map as the
175 last parameter to any of the log macros or the API functions, or
176 by setting process metadata with set_process_metadata/1 or
177 update_process_metadata/1.
178 Logger merges all the metadata maps before forwarding the log
180 event to the handlers. If the same keys occur, values from the
181 log call overwrite process metadata, which in turn overwrite
182 values set by Logger.
183 The following custom metadata keys have special meaning:
185 domain:
187 The value associated with this key is used by filters for
188 grouping log events originating from, for example, specific
189 functional areas. See logger_filters:domain/2 for a descrip‐
190 tion of how this field can be used.
191 report_cb:
193 If the log message is specified as a report(), the report_cb
194 key can be associated with a fun (report callback) that con‐
195 verts the report to a format string and arguments, or
196 directly to a string. See the type definition of
197 report_cb(), and section Log Message in the User's Guide for
198 more information about report callbacks.
199 msg_fun() =
201 fun((term()) ->
202 {io:format(), [term()]} |
203 report() |
204 unicode:chardata())
205 olp_config() =
207 #{sync_mode_qlen => integer() >= 0,
208 drop_mode_qlen => integer() >= 1,
209 flush_qlen => integer() >= 1,
210 burst_limit_enable => boolean(),
211 burst_limit_max_count => integer() >= 1,
212 burst_limit_window_time => integer() >= 1,
213 overload_kill_enable => boolean(),
214 overload_kill_qlen => integer() >= 1,
215 overload_kill_mem_size => integer() >= 1,
216 overload_kill_restart_after => integer() >= 0 | infinity}
217 primary_config() =
219 #{level => level() | all | none,
220 filter_default => log | stop,
221 filters => [{filter_id(), filter()}]}
222 Primary configuration data for Logger. The following default
224 values apply:
225 * level => info
227 * filter_default => log
229 * filters => []
231 report() = map() | [{atom(), term()}]
233 report_cb() =
235 fun((report()) -> {io:format(), [term()]}) |
236 fun((report(), report_cb_config()) -> unicode:chardata())
237 A fun which converts a report() to a format string and argu‐
239 ments, or directly to a string. See section Log Message in the
240 User's Guide for more information.
241 report_cb_config() =
243 #{depth := integer() >= 1 | unlimited,
244 chars_limit := integer() >= 1 | unlimited,
245 single_line := boolean()}
246 timestamp() = integer()
248 A timestamp produced with logger:timestamp().
250
252 The following macros are defined in logger.hrl, which is included in a
253 module with the directive
254 -include_lib("kernel/include/logger.hrl").
256 * ?LOG_EMERGENCY(StringOrReport[,Metadata])
258 * ?LOG_EMERGENCY(FunOrFormat,Args[,Metadata])
260 * ?LOG_ALERT(StringOrReport[,Metadata])
262 * ?LOG_ALERT(FunOrFormat,Args[,Metadata])
264 * ?LOG_CRITICAL(StringOrReport[,Metadata])
266 * ?LOG_CRITICAL(FunOrFormat,Args[,Metadata])
268 * ?LOG_ERROR(StringOrReport[,Metadata])
270 * ?LOG_ERROR(FunOrFormat,Args[,Metadata])
272 * ?LOG_WARNING(StringOrReport[,Metadata])
274 * ?LOG_WARNING(FunOrFormat,Args[,Metadata])
276 * ?LOG_NOTICE(StringOrReport[,Metadata])
278 * ?LOG_NOTICE(FunOrFormat,Args[,Metadata])
280 * ?LOG_INFO(StringOrReport[,Metadata])
282 * ?LOG_INFO(FunOrFormat,Args[,Metadata])
284 * ?LOG_DEBUG(StringOrReport[,Metadata])
286 * ?LOG_DEBUG(FunOrFormat,Args[,Metadata])
288 * ?LOG(Level,StringOrReport[,Metadata])
290 * ?LOG(Level,FunOrFormat,Args[,Metadata])
292 All macros expand to a call to Logger, where Level is taken from the
294 macro name, or from the first argument in the case of the ?LOG macro.
295 Location data is added to the metadata as described under the meta‐
296 data() type definition.
297 The call is wrapped in a case statement and will be evaluated only if
299 Level is equal to or below the configured log level.
300
303 emergency(StringOrReport[,Metadata])
304 emergency(Format,Args[,Metadata])
305 emergency(Fun,FunArgs[,Metadata])
306 Equivalent to log(emergency,...).
308 alert(StringOrReport[,Metadata])
310 alert(Format,Args[,Metadata])
311 alert(Fun,FunArgs[,Metadata])
312 Equivalent to log(alert,...).
314 critical(StringOrReport[,Metadata])
316 critical(Format,Args[,Metadata])
317 critical(Fun,FunArgs[,Metadata])
318 Equivalent to log(critical,...).
320 error(StringOrReport[,Metadata])
322 error(Format,Args[,Metadata])
323 error(Fun,FunArgs[,Metadata])
324 Equivalent to log(error,...).
326 warning(StringOrReport[,Metadata])
328 warning(Format,Args[,Metadata])
329 warning(Fun,FunArgs[,Metadata])
330 Equivalent to log(warning,...).
332 notice(StringOrReport[,Metadata])
334 notice(Format,Args[,Metadata])
335 notice(Fun,FunArgs[,Metadata])
336 Equivalent to log(notice,...).
338 info(StringOrReport[,Metadata])
340 info(Format,Args[,Metadata])
341 info(Fun,FunArgs[,Metadata])
342 Equivalent to log(info,...).
344 debug(StringOrReport[,Metadata])
346 debug(Format,Args[,Metadata])
347 debug(Fun,FunArgs[,Metadata])
348 Equivalent to log(debug,...).
350 log(Level, StringOrReport) -> ok
352 log(Level, StringOrReport, Metadata) -> ok
354 log(Level, Format, Args) -> ok
356 log(Level, Fun, FunArgs) -> ok
358 log(Level, Format, Args, Metadata) -> ok
360 log(Level, Fun, FunArgs, Metadata) -> ok
362 Types:
364 Level = level()
366 StringOrReport = unicode:chardata() | report()
367 Format = io:format()
368 Args = [term()]
369 Fun = msg_fun()
370 FunArgs = term()
371 Metadata = metadata()
372 Log the given message.
374
377 add_handler(HandlerId, Module, Config) -> ok | {error, term()}
378 Types:
380 HandlerId = handler_id()
382 Module = module()
383 Config = handler_config()
384 Add a handler with the given configuration.
386 HandlerId is a unique identifier which must be used in all sub‐
388 sequent calls referring to this handler.
389 add_handler_filter(HandlerId, FilterId, Filter) ->
391 ok | {error, term()}
392 Types:
394 HandlerId = handler_id()
396 FilterId = filter_id()
397 Filter = filter()
398 Add a filter to the specified handler.
400 The filter fun is called with the log event as the first parame‐
402 ter, and the specified filter_args() as the second parameter.
403 The return value of the fun specifies if a log event is to be
405 discarded or forwarded to the handler callback:
406 log_event():
408 The filter passed. The next handler filter, if any, is
409 applied. If no more filters exist for this handler, the log
410 event is forwarded to the handler callback.
411 stop:
413 The filter did not pass, and the log event is immediately
414 discarded.
415 ignore:
417 The filter has no knowledge of the log event. The next han‐
418 dler filter, if any, is applied. If no more filters exist
419 for this handler, the value of the filter_default configura‐
420 tion parameter for the handler specifies if the log event
421 shall be discarded or forwarded to the handler callback.
422 See section Filters in the User's Guide for more information
424 about filters.
425 Some built-in filters exist. These are defined in logger_fil‐
427 ters.
428 add_handlers(Application) -> ok | {error, term()}
430 Types:
432 Application = atom()
434 Reads the application configuration parameter logger and calls
436 add_handlers/1 with its contents.
437 add_handlers(HandlerConfig) -> ok | {error, term()}
439 Types:
441 HandlerConfig = [config_handler()]
443 config_handler() =
444 {handler, handler_id(), module(), handler_config()}
445 This function should be used by custom Logger handlers to make
447 configuration consistent no matter which handler the system
448 uses. Normal usage is to add a call to logger:add_handlers/1
449 just after the processes that the handler needs are started, and
450 pass the application's logger configuration as the argument. For
451 example:
452 -behaviour(application).
454 start(_, []) ->
455 case supervisor:start_link({local, my_sup}, my_sup, []) of
456 {ok, Pid} ->
457 ok = logger:add_handlers(my_app),
458 {ok, Pid, []};
459 Error -> Error
460 end.
461 This reads the logger configuration parameter from the my_app
463 application and starts the configured handlers. The contents of
464 the configuration use the same rules as the logger handler con‐
465 figuration.
466 If the handler is meant to replace the default handler, the Ker‐
468 nel's default handler have to be disabled before the new handler
469 is added. A sys.config file that disables the Kernel handler and
470 adds a custom handler could look like this:
471 [{kernel,
473 [{logger,
474 %% Disable the default Kernel handler
475 [{handler, default, undefined}]}]},
476 {my_app,
477 [{logger,
478 %% Enable this handler as the default
479 [{handler, default, my_handler, #{}}]}]}].
480 add_primary_filter(FilterId, Filter) -> ok | {error, term()}
483 Types:
485 FilterId = filter_id()
487 Filter = filter()
488 Add a primary filter to Logger.
490 The filter fun is called with the log event as the first parame‐
492 ter, and the specified filter_args() as the second parameter.
493 The return value of the fun specifies if a log event is to be
495 discarded or forwarded to the handlers:
496 log_event():
498 The filter passed. The next primary filter, if any, is
499 applied. If no more primary filters exist, the log event is
500 forwarded to the handler part of Logger, where handler fil‐
501 ters are applied.
502 stop:
504 The filter did not pass, and the log event is immediately
505 discarded.
506 ignore:
508 The filter has no knowledge of the log event. The next pri‐
509 mary filter, if any, is applied. If no more primary filters
510 exist, the value of the primary filter_default configuration
511 parameter specifies if the log event shall be discarded or
512 forwarded to the handler part.
513 See section Filters in the User's Guide for more information
515 about filters.
516 Some built-in filters exist. These are defined in logger_fil‐
518 ters.
519 get_config() ->
521 #{primary => primary_config(),
522 handlers => [handler_config()],
523 proxy => olp_config(),
524 module_levels =>
525 [{module(), level() | all | none}]}
526 Look up all current Logger configuration, including primary,
528 handler, and proxy configuration, and module level settings.
529 get_handler_config() -> [Config]
531 Types:
533 Config = handler_config()
535 Look up the current configuration for all handlers.
537 get_handler_config(HandlerId) -> {ok, Config} | {error, term()}
539 Types:
541 HandlerId = handler_id()
543 Config = handler_config()
544 Look up the current configuration for the given handler.
546 get_handler_ids() -> [HandlerId]
548 Types:
550 HandlerId = handler_id()
552 Look up the identities for all installed handlers.
554 get_primary_config() -> Config
556 Types:
558 Config = primary_config()
560 Look up the current primary configuration for Logger.
562 get_proxy_config() -> Config
564 Types:
566 Config = olp_config()
568 Look up the current configuration for the Logger proxy.
570 For more information about the proxy, see section Logger Proxy
572 in the Kernel User's Guide.
573 get_module_level() -> [{Module, Level}]
575 Types:
577 Module = module()
579 Level = level() | all | none
580 Look up all current module levels. Returns a list containing one
582 {Module,Level} element for each module for which the module
583 level was previously set with set_module_level/2.
584 get_module_level(Modules) -> [{Module, Level}]
586 Types:
588 Modules = [Module] | Module
590 Module = module()
591 Level = level() | all | none
592 Look up the current level for the given modules. Returns a list
594 containing one {Module,Level} element for each of the given mod‐
595 ules for which the module level was previously set with set_mod‐
596 ule_level/2.
597 get_process_metadata() -> Meta | undefined
599 Types:
601 Meta = metadata()
603 Retrieve data set with set_process_metadata/1 or
605 update_process_metadata/1.
606 i() -> ok
608 i(What) -> ok
610 Types:
612 What = primary | handlers | proxy | modules | handler_id()
614 Pretty print the Logger configuration.
616 remove_handler(HandlerId) -> ok | {error, term()}
618 Types:
620 HandlerId = handler_id()
622 Remove the handler identified by HandlerId.
624 remove_handler_filter(HandlerId, FilterId) -> ok | {error, term()}
626 Types:
628 HandlerId = handler_id()
630 FilterId = filter_id()
631 Remove the filter identified by FilterId from the handler iden‐
633 tified by HandlerId.
634 remove_primary_filter(FilterId) -> ok | {error, term()}
636 Types:
638 FilterId = filter_id()
640 Remove the primary filter identified by FilterId from Logger.
642 set_application_level(Application, Level) ->
644 ok | {error, not_loaded}
645 Types:
647 Application = atom()
649 Level = level() | all | none
650 Set the log level for all the modules of the specified applica‐
652 tion.
653 This function is a convenience function that calls log‐
655 ger:set_module_level/2 for each module associated with an appli‐
656 cation.
657 set_handler_config(HandlerId, Config) -> ok | {error, term()}
659 Types:
661 HandlerId = handler_id()
663 Config = handler_config()
664 Set configuration data for the specified handler. This over‐
666 writes the current handler configuration.
667 To modify the existing configuration, use update_handler_con‐
669 fig/2, or, if a more complex merge is needed, read the current
670 configuration with get_handler_config/1, then do the merge
671 before writing the new configuration back with this function.
672 If a key is removed compared to the current configuration, and
674 the key is known by Logger, the default value is used. If it is
675 a custom key, then it is up to the handler implementation if the
676 value is removed or a default value is inserted.
677 set_handler_config(HandlerId, Key :: level, Level) -> Return
679 set_handler_config(HandlerId,
681 Key :: filter_default,
682 FilterDefault) ->
683 Return
684 set_handler_config(HandlerId, Key :: filters, Filters) -> Return
686 set_handler_config(HandlerId, Key :: formatter, Formatter) ->
688 Return
689 set_handler_config(HandlerId, Key :: config, Config) -> Return
691 Types:
693 HandlerId = handler_id()
695 Level = level() | all | none
696 FilterDefault = log | stop
697 Filters = [{filter_id(), filter()}]
698 Formatter = {module(), formatter_config()}
699 Config = term()
700 Return = ok | {error, term()}
701 Add or update configuration data for the specified handler. If
703 the given Key already exists, its associated value will be
704 changed to the given value. If it does not exist, it will be
705 added.
706 If the value is incomplete, which for example can be the case
708 for the config key, it is up to the handler implementation how
709 the unspecified parts are set. For all handlers in the Kernel
710 application, unspecified data for the config key is set to
711 default values. To update only specified data, and keep the
712 existing configuration for the rest, use update_handler_con‐
713 fig/3.
714 See the definition of the handler_config() type for more infor‐
716 mation about the different parameters.
717 set_primary_config(Config) -> ok | {error, term()}
719 Types:
721 Config = primary_config()
723 Set primary configuration data for Logger. This overwrites the
725 current configuration.
726 To modify the existing configuration, use update_primary_con‐
728 fig/1, or, if a more complex merge is needed, read the current
729 configuration with get_primary_config/0, then do the merge
730 before writing the new configuration back with this function.
731 If a key is removed compared to the current configuration, the
733 default value is used.
734 set_primary_config(Key :: level, Level) -> ok | {error, term()}
736 set_primary_config(Key :: filter_default, FilterDefault) ->
738 ok | {error, term()}
739 set_primary_config(Key :: filters, Filters) ->
741 ok | {error, term()}
742 Types:
744 Level = level() | all | none
746 FilterDefault = log | stop
747 Filters = [{filter_id(), filter()}]
748 Add or update primary configuration data for Logger. If the
750 given Key already exists, its associated value will be changed
751 to the given value. If it does not exist, it will be added.
752 set_proxy_config(Config) -> ok | {error, term()}
754 Types:
756 Config = olp_config()
758 Set configuration data for the Logger proxy. This overwrites the
760 current proxy configuration. Keys that are not specified in the
761 Config map gets default values.
762 To modify the existing configuration, use update_proxy_config/1,
764 or, if a more complex merge is needed, read the current configu‐
765 ration with get_proxy_config/0, then do the merge before writing
766 the new configuration back with this function.
767 For more information about the proxy, see section Logger Proxy
769 in the Kernel User's Guide.
770 set_module_level(Modules, Level) -> ok | {error, term()}
772 Types:
774 Modules = [module()] | module()
776 Level = level() | all | none
777 Set the log level for the specified modules.
779 The log level for a module overrides the primary log level of
781 Logger for log events originating from the module in question.
782 Notice, however, that it does not override the level configura‐
783 tion for any handler.
784 For example: Assume that the primary log level for Logger is
786 info, and there is one handler, h1, with level info and one han‐
787 dler, h2, with level debug.
788 With this configuration, no debug messages will be logged, since
790 they are all stopped by the primary log level.
791 If the level for mymodule is now set to debug, then debug events
793 from this module will be logged by the handler h2, but not by
794 handler h1.
795 Debug events from other modules are still not logged.
797 To change the primary log level for Logger, use set_primary_con‐
799 fig(level, Level).
800 To change the log level for a handler, use set_handler_con‐
802 fig(HandlerId, level, Level).
803 Note:
805 The originating module for a log event is only detected if the
806 key mfa exists in the metadata, and is associated with {Module,
807 Function, Arity}. When log macros are used, this association is
808 automatically added to all log events. If an API function is
809 called directly, without using a macro, the logging client must
810 explicitly add this information if module levels shall have any
811 effect.
812 set_process_metadata(Meta) -> ok
815 Types:
817 Meta = metadata()
819 Set metadata which Logger shall automatically insert in all log
821 events produced on the current process.
822 Location data produced by the log macros, and/or metadata given
824 as argument to the log call (API function or macro), are merged
825 with the process metadata. If the same keys occur, values from
826 the metadata argument to the log call overwrite values from the
827 process metadata, which in turn overwrite values from the loca‐
828 tion data.
829 Subsequent calls to this function overwrites previous data set.
831 To update existing data instead of overwriting it, see
832 update_process_metadata/1.
833 unset_application_level(Application) -> ok | {error, not_loaded}
835 Types:
837 Application = atom()
839 Unset the log level for all the modules of the specified appli‐
841 cation.
842 This function is a convinience function that calls log‐
844 ger:unset_module_level/2 for each module associated with an
845 application.
846 unset_module_level() -> ok
848 Remove module specific log settings. After this, the primary log
850 level is used for all modules.
851 unset_module_level(Modules) -> ok
853 Types:
855 Modules = [module()] | module()
857 Remove module specific log settings. After this, the primary log
859 level is used for the specified modules.
860 unset_process_metadata() -> ok
862 Delete data set with set_process_metadata/1 or
864 update_process_metadata/1.
865 update_formatter_config(HandlerId, FormatterConfig) ->
867 ok | {error, term()}
868 Types:
870 HandlerId = handler_id()
872 FormatterConfig = formatter_config()
873 Update the formatter configuration for the specified handler.
875 The new configuration is merged with the existing formatter con‐
877 figuration.
878 To overwrite the existing configuration without any merge, use
880 set_handler_config(HandlerId, formatter, {FormatterModule, FormatterConfig}).
882 update_formatter_config(HandlerId, Key, Value) ->
884 ok | {error, term()}
885 Types:
887 HandlerId = handler_id()
889 Key = atom()
890 Value = term()
891 Update the formatter configuration for the specified handler.
893 This is equivalent to
895 update_formatter_config(HandlerId, #{Key => Value})
897 update_handler_config(HandlerId, Config) -> ok | {error, term()}
899 Types:
901 HandlerId = handler_id()
903 Config = handler_config()
904 Update configuration data for the specified handler. This func‐
906 tion behaves as if it was implemented as follows:
907 {ok, {_, Old}} = logger:get_handler_config(HandlerId),
909 logger:set_handler_config(HandlerId, maps:merge(Old, Config)).
910 To overwrite the existing configuration without any merge, use
913 set_handler_config/2.
914 update_handler_config(HandlerId, Key :: level, Level) -> Return
916 update_handler_config(HandlerId,
918 Key :: filter_default,
919 FilterDefault) ->
920 Return
921 update_handler_config(HandlerId, Key :: filters, Filters) ->
923 Return
924 update_handler_config(HandlerId, Key :: formatter, Formatter) ->
926 Return
927 update_handler_config(HandlerId, Key :: config, Config) -> Return
929 Types:
931 HandlerId = handler_id()
933 Level = level() | all | none
934 FilterDefault = log | stop
935 Filters = [{filter_id(), filter()}]
936 Formatter = {module(), formatter_config()}
937 Config = term()
938 Return = ok | {error, term()}
939 Add or update configuration data for the specified handler. If
941 the given Key already exists, its associated value will be
942 changed to the given value. If it does not exist, it will be
943 added.
944 If the value is incomplete, which for example can be the case
946 for the config key, it is up to the handler implementation how
947 the unspecified parts are set. For all handlers in the Kernel
948 application, unspecified data for the config key is not changed.
949 To reset unspecified data to default values, use set_han‐
950 dler_config/3.
951 See the definition of the handler_config() type for more infor‐
953 mation about the different parameters.
954 update_primary_config(Config) -> ok | {error, term()}
956 Types:
958 Config = primary_config()
960 Update primary configuration data for Logger. This function
962 behaves as if it was implemented as follows:
963 Old = logger:get_primary_config(),
965 logger:set_primary_config(maps:merge(Old, Config)).
966 To overwrite the existing configuration without any merge, use
969 set_primary_config/1.
970 update_process_metadata(Meta) -> ok
972 Types:
974 Meta = metadata()
976 Set or update metadata to use when logging from current process
978 If process metadata exists for the current process, this func‐
980 tion behaves as if it was implemented as follows:
981 logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
983 If no process metadata exists, the function behaves as
986 set_process_metadata/1.
987 update_proxy_config(Config) -> ok | {error, term()}
989 Types:
991 Config = olp_config()
993 Update configuration data for the Logger proxy. This function
995 behaves as if it was implemented as follows:
996 Old = logger:get_proxy_config(),
998 logger:set_proxy_config(maps:merge(Old, Config)).
999 To overwrite the existing configuration without any merge, use
1002 set_proxy_config/1.
1003 For more information about the proxy, see section Logger Proxy
1005 in the Kernel User's Guide.
1006
1009 compare_levels(Level1, Level2) -> eq | gt | lt
1010 Types:
1012 Level1 = Level2 = level()
1014 Compare the severity of two log levels. Returns gt if Level1 is
1016 more severe than Level2, lt if Level1 is less severe, and eq if
1017 the levels are equal.
1018 format_report(Report) -> FormatArgs
1020 Types:
1022 Report = report()
1024 FormatArgs = {io:format(), [term()]}
1025 Convert a log message on report form to {Format, Args}. This is
1027 the default report callback used by logger_formatter when no
1028 custom report callback is found. See section Log Message in the
1029 Kernel User's Guide for information about report callbacks and
1030 valid forms of log messages.
1031 The function produces lines of Key: Value from key-value lists.
1033 Strings are printed with ~ts and other terms with ~tp.
1034 If Report is a map, it is converted to a key-value list before
1036 formatting as such.
1037 timestamp() -> timestamp()
1039 Return a timestamp that can be inserted as the time field in the
1041 meta data for a log event. It is produced with os:sys‐
1042 tem_time(microsecond).
1043 Notice that Logger automatically inserts a timestamp in the meta
1045 data unless it already exists. This function is exported for the
1046 rare case when the timestamp must be taken at a different point
1047 in time than when the log event is issued.
1048
1050 The following functions are to be exported from a handler callback mod‐
1051 ule.
1052
1054 HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason}
1055 Types:
1057 Config1 = Config2 = handler_config()
1059 Reason = term()
1060 This callback function is optional.
1062 The function is called on a temporary process when an new han‐
1064 dler is about to be added. The purpose is to verify the configu‐
1065 ration and initiate all resources needed by the handler.
1066 The handler identity is associated with the id key in Config1.
1068 If everything succeeds, the callback function can add possible
1070 default values or internal state values to the configuration,
1071 and return the adjusted map in {ok,Config2}.
1072 If the configuration is faulty, or if the initiation fails, the
1074 callback function must return {error,Reason}.
1075 HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Con‐
1077 fig} | {error, Reason}
1078 Types:
1080 SetOrUpdate = set | update
1082 OldConfig = NewConfig = Config = handler_config()
1083 Reason = term()
1084 This callback function is optional.
1086 The function is called on a temporary process when the configu‐
1088 ration for a handler is about to change. The purpose is to ver‐
1089 ify and act on the new configuration.
1090 OldConfig is the existing configuration and NewConfig is the new
1092 configuration.
1093 The handler identity is associated with the id key in OldConfig.
1095 SetOrUpdate has the value set if the configuration change origi‐
1097 nates from a call to set_handler_config/2,3, and update if it
1098 originates from update_handler_config/2,3. The handler can use
1099 this parameteter to decide how to update the value of the config
1100 field, that is, the handler specific configuration data. Typi‐
1101 cally, if SetOrUpdate equals set, values that are not specified
1102 must be given their default values. If SetOrUpdate equals
1103 update, the values found in OldConfig must be used instead.
1104 If everything succeeds, the callback function must return a pos‐
1106 sibly adjusted configuration in {ok,Config}.
1107 If the configuration is faulty, the callback function must
1109 return {error,Reason}.
1110 HModule:filter_config(Config) -> FilteredConfig
1112 Types:
1114 Config = FilteredConfig = handler_config()
1116 This callback function is optional.
1118 The function is called when one of the Logger API functions for
1120 fetching the handler configuration is called, for example log‐
1121 ger:get_handler_config/1.
1122 It allows the handler to remove internal data fields from its
1124 configuration data before it is returned to the caller.
1125 HModule:log(LogEvent, Config) -> void()
1127 Types:
1129 LogEvent = log_event()
1131 Config = handler_config()
1132 This callback function is mandatory.
1134 The function is called when all primary filters and all handler
1136 filters for the handler in question have passed for the given
1137 log event. It is called on the client process, that is, the
1138 process that issued the log event.
1139 The handler identity is associated with the id key in Config.
1141 The handler must log the event.
1143 The return value from this function is ignored by Logger.
1145 HModule:removing_handler(Config) -> ok
1147 Types:
1149 Config = handler_config()
1151 This callback function is optional.
1153 The function is called on a temporary process when a handler is
1155 about to be removed. The purpose is to release all resources
1156 used by the handler.
1157 The handler identity is associated with the id key in Config.
1159 The return value is ignored by Logger.
1161
1163 The following functions are to be exported from a formatter callback
1164 module.
1165
1167 FModule:check_config(FConfig) -> ok | {error, Reason}
1168 Types:
1170 FConfig = formatter_config()
1172 Reason = term()
1173 This callback function is optional.
1175 The function is called by a Logger when formatter configuration
1177 is set or modified. The formatter must validate the given con‐
1178 figuration and return ok if it is correct, and {error,Reason} if
1179 it is faulty.
1180 The following Logger API functions can trigger this callback:
1182 * logger:add_handler/3
1184 * logger:set_handler_config/2,3
1186 * logger:update_handler_config/2,3
1188 * logger:update_formatter_config/2
1190 See logger_formatter(3) for an example implementation. log‐
1192 ger_formatter is the default formatter used by Logger.
1193 FModule:format(LogEvent, FConfig) -> FormattedLogEntry
1195 Types:
1197 LogEvent = log_event()
1199 FConfig = formatter_config()
1200 FormattedLogEntry = unicode:chardata()
1201 This callback function is mandatory.
1203 The function can be called by a log handler to convert a log
1205 event term to a printable string. The returned value can, for
1206 example, be printed as a log entry to the console or a file
1207 using io:put_chars/1,2.
1208 See logger_formatter(3) for an example implementation. log‐
1210 ger_formatter is the default formatter used by Logger.
1211
1213 config(4), erlang(3), io(3), logger_disk_log_h(3), logger_filters(3),
1214 logger_formatter(3), logger_std_h(3), unicode(3)
1215Ericsson AB kernel 6.3.1.1 logger(3)