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 | alert | critical | error | warning | notice |
126 info | debug
127 The severity level for the message to be logged.
129 log_event() =
131 #{level := level(),
132 msg :=
133 {io:format(), [term()]} |
134 {report, report()} |
135 {string, unicode:chardata()},
136 meta := metadata()}
137 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 Metadata for the log event.
150 Logger adds the following metadata to each log event:
152 * pid => self()
154 * gl => group_leader()
156 * time => logger:timestamp()
158 When a log macro is used, Logger also inserts location informa‐
160 tion:
161 * mfa => {?MODULE, ?FUNCTION_NAME, ?FUNCTION_ARITY}
163 * file => ?FILE
165 * line => ?LINE
167 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 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 The following custom metadata keys have special meaning:
179 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 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 msg_fun() =
195 fun((term()) ->
196 {io:format(), [term()]} |
197 report() |
198 unicode:chardata())
199 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 primary_config() =
213 #{level => level() | all | none,
214 filter_default => log | stop,
215 filters => [{filter_id(), filter()}]}
216 Primary configuration data for Logger. The following default
218 values apply:
219 * level => info
221 * filter_default => log
223 * filters => []
225 report() = map() | [{atom(), term()}]
227 report_cb() =
229 fun((report()) -> {io:format(), [term()]}) |
230 fun((report(), report_cb_config()) -> unicode:chardata())
231 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 report_cb_config() =
237 #{depth := integer() >= 1 | unlimited,
238 chars_limit := integer() >= 1 | unlimited,
239 single_line := boolean()}
240 timestamp() = integer()
242 A timestamp produced with logger:timestamp().
244
246 The following macros are defined in logger.hrl, which is included in a
247 module with the directive
248 -include_lib("kernel/include/logger.hrl").
250 * ?LOG_EMERGENCY(StringOrReport[,Metadata])
252 * ?LOG_EMERGENCY(FunOrFormat,Args[,Metadata])
254 * ?LOG_ALERT(StringOrReport[,Metadata])
256 * ?LOG_ALERT(FunOrFormat,Args[,Metadata])
258 * ?LOG_CRITICAL(StringOrReport[,Metadata])
260 * ?LOG_CRITICAL(FunOrFormat,Args[,Metadata])
262 * ?LOG_ERROR(StringOrReport[,Metadata])
264 * ?LOG_ERROR(FunOrFormat,Args[,Metadata])
266 * ?LOG_WARNING(StringOrReport[,Metadata])
268 * ?LOG_WARNING(FunOrFormat,Args[,Metadata])
270 * ?LOG_NOTICE(StringOrReport[,Metadata])
272 * ?LOG_NOTICE(FunOrFormat,Args[,Metadata])
274 * ?LOG_INFO(StringOrReport[,Metadata])
276 * ?LOG_INFO(FunOrFormat,Args[,Metadata])
278 * ?LOG_DEBUG(StringOrReport[,Metadata])
280 * ?LOG_DEBUG(FunOrFormat,Args[,Metadata])
282 * ?LOG(Level,StringOrReport[,Metadata])
284 * ?LOG(Level,FunOrFormat,Args[,Metadata])
286 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 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
297 emergency(StringOrReport[,Metadata])
298 emergency(Format,Args[,Metadata])
299 emergency(Fun,FunArgs[,Metadata])
300 Equivalent to log(emergency,...).
302 alert(StringOrReport[,Metadata])
304 alert(Format,Args[,Metadata])
305 alert(Fun,FunArgs[,Metadata])
306 Equivalent to log(alert,...).
308 critical(StringOrReport[,Metadata])
310 critical(Format,Args[,Metadata])
311 critical(Fun,FunArgs[,Metadata])
312 Equivalent to log(critical,...).
314 error(StringOrReport[,Metadata])
316 error(Format,Args[,Metadata])
317 error(Fun,FunArgs[,Metadata])
318 Equivalent to log(error,...).
320 warning(StringOrReport[,Metadata])
322 warning(Format,Args[,Metadata])
323 warning(Fun,FunArgs[,Metadata])
324 Equivalent to log(warning,...).
326 notice(StringOrReport[,Metadata])
328 notice(Format,Args[,Metadata])
329 notice(Fun,FunArgs[,Metadata])
330 Equivalent to log(notice,...).
332 info(StringOrReport[,Metadata])
334 info(Format,Args[,Metadata])
335 info(Fun,FunArgs[,Metadata])
336 Equivalent to log(info,...).
338 debug(StringOrReport[,Metadata])
340 debug(Format,Args[,Metadata])
341 debug(Fun,FunArgs[,Metadata])
342 Equivalent to log(debug,...).
344 log(Level, StringOrReport) -> ok
346 log(Level, StringOrReport, Metadata) -> ok
348 log(Level, Format, Args) -> ok
350 log(Level, Fun, FunArgs) -> ok
352 log(Level, Format, Args, Metadata) -> ok
354 log(Level, Fun, FunArgs, Metadata) -> ok
356 Types:
358 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 Log the given message.
368
371 add_handler(HandlerId, Module, Config) -> ok | {error, term()}
372 Types:
374 HandlerId = handler_id()
376 Module = module()
377 Config = handler_config()
378 Add a handler with the given configuration.
380 HandlerId is a unique identifier which must be used in all sub‐
382 sequent calls referring to this handler.
383 add_handler_filter(HandlerId, FilterId, Filter) ->
385 ok | {error, term()}
386 Types:
388 HandlerId = handler_id()
390 FilterId = filter_id()
391 Filter = filter()
392 Add a filter to the specified handler.
394 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 The return value of the fun specifies if a log event is to be
399 discarded or forwarded to the handler callback:
400 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 stop:
407 The filter did not pass, and the log event is immediately
408 discarded.
409 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 See section Filters in the User's Guide for more information
418 about filters.
419 Some built-in filters exist. These are defined in logger_fil‐
421 ters.
422 add_handlers(Application) -> ok | {error, term()}
424 Types:
426 Application = atom()
428 Reads the application configuration parameter logger and calls
430 add_handlers/1 with its contents.
431 add_handlers(HandlerConfig) -> ok | {error, term()}
433 Types:
435 HandlerConfig = [config_handler()]
437 config_handler() =
438 {handler, handler_id(), module(), handler_config()}
439 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 -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 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 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 [{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 add_primary_filter(FilterId, Filter) -> ok | {error, term()}
477 Types:
479 FilterId = filter_id()
481 Filter = filter()
482 Add a primary filter to Logger.
484 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 The return value of the fun specifies if a log event is to be
489 discarded or forwarded to the handlers:
490 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 stop:
498 The filter did not pass, and the log event is immediately
499 discarded.
500 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 See section Filters in the User's Guide for more information
509 about filters.
510 Some built-in filters exist. These are defined in logger_fil‐
512 ters.
513 get_config() ->
515 #{primary => primary_config(),
516 handlers => [handler_config()],
517 proxy => olp_config(),
518 module_levels =>
519 [{module(), level() | all | none}]}
520 Look up all current Logger configuration, including primary,
522 handler, and proxy configuration, and module level settings.
523 get_handler_config() -> [Config]
525 Types:
527 Config = handler_config()
529 Look up the current configuration for all handlers.
531 get_handler_config(HandlerId) -> {ok, Config} | {error, term()}
533 Types:
535 HandlerId = handler_id()
537 Config = handler_config()
538 Look up the current configuration for the given handler.
540 get_handler_ids() -> [HandlerId]
542 Types:
544 HandlerId = handler_id()
546 Look up the identities for all installed handlers.
548 get_primary_config() -> Config
550 Types:
552 Config = primary_config()
554 Look up the current primary configuration for Logger.
556 get_proxy_config() -> Config
558 Types:
560 Config = olp_config()
562 Look up the current configuration for the Logger proxy.
564 For more information about the proxy, see section Logger Proxy
566 in the Kernel User's Guide.
567 get_module_level() -> [{Module, Level}]
569 Types:
571 Module = module()
573 Level = level() | all | none
574 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 get_module_level(Modules) -> [{Module, Level}]
580 Types:
582 Modules = [Module] | Module
584 Module = module()
585 Level = level() | all | none
586 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 get_process_metadata() -> Meta | undefined
593 Types:
595 Meta = metadata()
597 Retrieve data set with set_process_metadata/1 or
599 update_process_metadata/1.
600 i() -> ok
602 i(What) -> ok
604 Types:
606 What = primary | handlers | proxy | modules | handler_id()
608 Pretty print the Logger configuration.
610 remove_handler(HandlerId) -> ok | {error, term()}
612 Types:
614 HandlerId = handler_id()
616 Remove the handler identified by HandlerId.
618 remove_handler_filter(HandlerId, FilterId) -> ok | {error, term()}
620 Types:
622 HandlerId = handler_id()
624 FilterId = filter_id()
625 Remove the filter identified by FilterId from the handler iden‐
627 tified by HandlerId.
628 remove_primary_filter(FilterId) -> ok | {error, term()}
630 Types:
632 FilterId = filter_id()
634 Remove the primary filter identified by FilterId from Logger.
636 set_application_level(Application, Level) ->
638 ok | {error, not_loaded}
639 Types:
641 Application = atom()
643 Level = level() | all | none
644 Set the log level for all the modules of the specified applica‐
646 tion.
647 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 set_handler_config(HandlerId, Config) -> ok | {error, term()}
653 Types:
655 HandlerId = handler_id()
657 Config = handler_config()
658 Set configuration data for the specified handler. This over‐
660 writes the current handler configuration.
661 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 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 set_handler_config(HandlerId, Key :: level, Level) -> Return
673 set_handler_config(HandlerId,
675 Key :: filter_default,
676 FilterDefault) ->
677 Return
678 set_handler_config(HandlerId, Key :: filters, Filters) -> Return
680 set_handler_config(HandlerId, Key :: formatter, Formatter) ->
682 Return
683 set_handler_config(HandlerId, Key :: config, Config) -> Return
685 Types:
687 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 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 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 See the definition of the handler_config() type for more infor‐
710 mation about the different parameters.
711 set_primary_config(Config) -> ok | {error, term()}
713 Types:
715 Config = primary_config()
717 Set primary configuration data for Logger. This overwrites the
719 current configuration.
720 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 If a key is removed compared to the current configuration, the
727 default value is used.
728 set_primary_config(Key :: level, Level) -> ok | {error, term()}
730 set_primary_config(Key :: filter_default, FilterDefault) ->
732 ok | {error, term()}
733 set_primary_config(Key :: filters, Filters) ->
735 ok | {error, term()}
736 Types:
738 Level = level() | all | none
740 FilterDefault = log | stop
741 Filters = [{filter_id(), filter()}]
742 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 set_proxy_config(Config) -> ok | {error, term()}
748 Types:
750 Config = olp_config()
752 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 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 For more information about the proxy, see section Logger Proxy
763 in the Kernel User's Guide.
764 set_module_level(Modules, Level) -> ok | {error, term()}
766 Types:
768 Modules = [module()] | module()
770 Level = level() | all | none
771 Set the log level for the specified modules.
773 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 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 With this configuration, no debug messages will be logged, since
784 they are all stopped by the primary log level.
785 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 Debug events from other modules are still not logged.
791 To change the primary log level for Logger, use set_primary_con‐
793 fig(level, Level).
794 To change the log level for a handler, use set_handler_con‐
796 fig(HandlerId, level, Level).
797 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 set_process_metadata(Meta) -> ok
809 Types:
811 Meta = metadata()
813 Set metadata which Logger shall automatically insert in all log
815 events produced on the current process.
816 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 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 unset_application_level(Application) -> ok | {error, not_loaded}
829 Types:
831 Application = atom()
833 Unset the log level for all the modules of the specified appli‐
835 cation.
836 This function is a convinience function that calls log‐
838 ger:unset_module_level/2 for each module associated with an
839 application.
840 unset_module_level() -> ok
842 Remove module specific log settings. After this, the primary log
844 level is used for all modules.
845 unset_module_level(Modules) -> ok
847 Types:
849 Modules = [module()] | module()
851 Remove module specific log settings. After this, the primary log
853 level is used for the specified modules.
854 unset_process_metadata() -> ok
856 Delete data set with set_process_metadata/1 or
858 update_process_metadata/1.
859 update_formatter_config(HandlerId, FormatterConfig) ->
861 ok | {error, term()}
862 Types:
864 HandlerId = handler_id()
866 FormatterConfig = formatter_config()
867 Update the formatter configuration for the specified handler.
869 The new configuration is merged with the existing formatter con‐
871 figuration.
872 To overwrite the existing configuration without any merge, use
874 set_handler_config(HandlerId, formatter, {FormatterModule, FormatterConfig}).
876 update_formatter_config(HandlerId, Key, Value) ->
878 ok | {error, term()}
879 Types:
881 HandlerId = handler_id()
883 Key = atom()
884 Value = term()
885 Update the formatter configuration for the specified handler.
887 This is equivalent to
889 update_formatter_config(HandlerId, #{Key => Value})
891 update_handler_config(HandlerId, Config) -> ok | {error, term()}
893 Types:
895 HandlerId = handler_id()
897 Config = handler_config()
898 Update configuration data for the specified handler. This func‐
900 tion behaves as if it was implemented as follows:
901 {ok, {_, Old}} = logger:get_handler_config(HandlerId),
903 logger:set_handler_config(HandlerId, maps:merge(Old, Config)).
904 To overwrite the existing configuration without any merge, use
907 set_handler_config/2.
908 update_handler_config(HandlerId, Key :: level, Level) -> Return
910 update_handler_config(HandlerId,
912 Key :: filter_default,
913 FilterDefault) ->
914 Return
915 update_handler_config(HandlerId, Key :: filters, Filters) ->
917 Return
918 update_handler_config(HandlerId, Key :: formatter, Formatter) ->
920 Return
921 update_handler_config(HandlerId, Key :: config, Config) -> Return
923 Types:
925 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 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 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 See the definition of the handler_config() type for more infor‐
947 mation about the different parameters.
948 update_primary_config(Config) -> ok | {error, term()}
950 Types:
952 Config = primary_config()
954 Update primary configuration data for Logger. This function
956 behaves as if it was implemented as follows:
957 Old = logger:get_primary_config(),
959 logger:set_primary_config(maps:merge(Old, Config)).
960 To overwrite the existing configuration without any merge, use
963 set_primary_config/1.
964 update_process_metadata(Meta) -> ok
966 Types:
968 Meta = metadata()
970 Set or update metadata to use when logging from current process
972 If process metadata exists for the current process, this func‐
974 tion behaves as if it was implemented as follows:
975 logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
977 If no process metadata exists, the function behaves as
980 set_process_metadata/1.
981 update_proxy_config(Config) -> ok | {error, term()}
983 Types:
985 Config = olp_config()
987 Update configuration data for the Logger proxy. This function
989 behaves as if it was implemented as follows:
990 Old = logger:get_proxy_config(),
992 logger:set_proxy_config(maps:merge(Old, Config)).
993 To overwrite the existing configuration without any merge, use
996 set_proxy_config/1.
997 For more information about the proxy, see section Logger Proxy
999 in the Kernel User's Guide.
1000
1003 compare_levels(Level1, Level2) -> eq | gt | lt
1004 Types:
1006 Level1 = Level2 = level() | all | none
1008 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 format_report(Report) -> FormatArgs
1014 Types:
1016 Report = report()
1018 FormatArgs = {io:format(), [term()]}
1019 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 The function produces lines of Key: Value from key-value lists.
1027 Strings are printed with ~ts and other terms with ~tp.
1028 If Report is a map, it is converted to a key-value list before
1030 formatting as such.
1031 timestamp() -> timestamp()
1033 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 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
1044 The following functions are to be exported from a handler callback mod‐
1045 ule.
1046
1048 HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason}
1049 Types:
1051 Config1 = Config2 = handler_config()
1053 Reason = term()
1054 This callback function is optional.
1056 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 The handler identity is associated with the id key in Config1.
1062 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 If the configuration is faulty, or if the initiation fails, the
1068 callback function must return {error,Reason}.
1069 HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Con‐
1071 fig} | {error, Reason}
1072 Types:
1074 SetOrUpdate = set | update
1076 OldConfig = NewConfig = Config = handler_config()
1077 Reason = term()
1078 This callback function is optional.
1080 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 OldConfig is the existing configuration and NewConfig is the new
1086 configuration.
1087 The handler identity is associated with the id key in OldConfig.
1089 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 If everything succeeds, the callback function must return a pos‐
1100 sibly adjusted configuration in {ok,Config}.
1101 If the configuration is faulty, the callback function must
1103 return {error,Reason}.
1104 HModule:filter_config(Config) -> FilteredConfig
1106 Types:
1108 Config = FilteredConfig = handler_config()
1110 This callback function is optional.
1112 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 It allows the handler to remove internal data fields from its
1118 configuration data before it is returned to the caller.
1119 HModule:log(LogEvent, Config) -> void()
1121 Types:
1123 LogEvent = log_event()
1125 Config = handler_config()
1126 This callback function is mandatory.
1128 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 The handler identity is associated with the id key in Config.
1135 The handler must log the event.
1137 The return value from this function is ignored by Logger.
1139 HModule:removing_handler(Config) -> ok
1141 Types:
1143 Config = handler_config()
1145 This callback function is optional.
1147 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 The handler identity is associated with the id key in Config.
1153 The return value is ignored by Logger.
1155
1157 The following functions are to be exported from a formatter callback
1158 module.
1159
1161 FModule:check_config(FConfig) -> ok | {error, Reason}
1162 Types:
1164 FConfig = formatter_config()
1166 Reason = term()
1167 This callback function is optional.
1169 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 The following Logger API functions can trigger this callback:
1176 * logger:add_handler/3
1178 * logger:set_handler_config/2,3
1180 * logger:update_handler_config/2,3
1182 * logger:update_formatter_config/2
1184 See logger_formatter(3) for an example implementation. log‐
1186 ger_formatter is the default formatter used by Logger.
1187 FModule:format(LogEvent, FConfig) -> FormattedLogEntry
1189 Types:
1191 LogEvent = log_event()
1193 FConfig = formatter_config()
1194 FormattedLogEntry = unicode:chardata()
1195 This callback function is mandatory.
1197 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 See logger_formatter(3) for an example implementation. log‐
1204 ger_formatter is the default formatter used by Logger.
1205
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)
1209Ericsson AB kernel 6.5 logger(3)