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 de‐
24 fault 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 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
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 in‐
102 serted by Logger, values taken from the two first parameters to
103 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(3)
114 manual pages for information about the specific configuration
115 for 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:
169 * specifying a map as the last parameter to any of the log
171 macros or the logger API functions.
172 * setting process metadata with set_process_metadata/1 or up‐
174 date_process_metadata/1.
175 * setting primary metadata with set_primary_config/1 or
177 through the kernel configuration parameter logger_metadata
178 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 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 The following custom metadata keys have special meaning:
191 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 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 msg_fun() =
207 fun((term()) ->
208 msg_fun_return() | {msg_fun_return(), metadata()})
209 msg_fun_return() =
211 {io:format(), [term()]} |
212 report() |
213 unicode:chardata() |
214 ignore
215 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 primary_config() =
229 #{level => level() | all | none,
230 metadata => metadata(),
231 filter_default => log | stop,
232 filters => [{filter_id(), filter()}]}
233 Primary configuration data for Logger. The following default
235 values apply:
236 * level => info
238 * filter_default => log
240 * filters => []
242 report() = map() | [{atom(), term()}]
244 report_cb() =
246 fun((report()) -> {io:format(), [term()]}) |
247 fun((report(), report_cb_config()) -> unicode:chardata())
248 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 report_cb_config() =
254 #{depth := integer() >= 1 | unlimited,
255 chars_limit := integer() >= 1 | unlimited,
256 single_line := boolean()}
257 timestamp() = integer()
259 A timestamp produced with logger:timestamp().
261
263 The following macros are defined in logger.hrl, which is included in a
264 module with the directive
265 -include_lib("kernel/include/logger.hrl").
267 * ?LOG_EMERGENCY(StringOrReport[,Metadata])
269 * ?LOG_EMERGENCY(FunOrFormat,Args[,Metadata])
271 * ?LOG_ALERT(StringOrReport[,Metadata])
273 * ?LOG_ALERT(FunOrFormat,Args[,Metadata])
275 * ?LOG_CRITICAL(StringOrReport[,Metadata])
277 * ?LOG_CRITICAL(FunOrFormat,Args[,Metadata])
279 * ?LOG_ERROR(StringOrReport[,Metadata])
281 * ?LOG_ERROR(FunOrFormat,Args[,Metadata])
283 * ?LOG_WARNING(StringOrReport[,Metadata])
285 * ?LOG_WARNING(FunOrFormat,Args[,Metadata])
287 * ?LOG_NOTICE(StringOrReport[,Metadata])
289 * ?LOG_NOTICE(FunOrFormat,Args[,Metadata])
291 * ?LOG_INFO(StringOrReport[,Metadata])
293 * ?LOG_INFO(FunOrFormat,Args[,Metadata])
295 * ?LOG_DEBUG(StringOrReport[,Metadata])
297 * ?LOG_DEBUG(FunOrFormat,Args[,Metadata])
299 * ?LOG(Level,StringOrReport[,Metadata])
301 * ?LOG(Level,FunOrFormat,Args[,Metadata])
303 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 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
314 emergency(StringOrReport[,Metadata])
315 emergency(Format,Args[,Metadata])
316 emergency(Fun,FunArgs[,Metadata])
317 Equivalent to log(emergency,...).
319 alert(StringOrReport[,Metadata])
321 alert(Format,Args[,Metadata])
322 alert(Fun,FunArgs[,Metadata])
323 Equivalent to log(alert,...).
325 critical(StringOrReport[,Metadata])
327 critical(Format,Args[,Metadata])
328 critical(Fun,FunArgs[,Metadata])
329 Equivalent to log(critical,...).
331 error(StringOrReport[,Metadata])
333 error(Format,Args[,Metadata])
334 error(Fun,FunArgs[,Metadata])
335 Equivalent to log(error,...).
337 warning(StringOrReport[,Metadata])
339 warning(Format,Args[,Metadata])
340 warning(Fun,FunArgs[,Metadata])
341 Equivalent to log(warning,...).
343 notice(StringOrReport[,Metadata])
345 notice(Format,Args[,Metadata])
346 notice(Fun,FunArgs[,Metadata])
347 Equivalent to log(notice,...).
349 info(StringOrReport[,Metadata])
351 info(Format,Args[,Metadata])
352 info(Fun,FunArgs[,Metadata])
353 Equivalent to log(info,...).
355 debug(StringOrReport[,Metadata])
357 debug(Format,Args[,Metadata])
358 debug(Fun,FunArgs[,Metadata])
359 Equivalent to log(debug,...).
361 log(Level, StringOrReport) -> ok
363 log(Level, StringOrReport, Metadata) -> ok
365 log(Level, Format, Args) -> ok
367 log(Level, Fun, FunArgs) -> ok
369 log(Level, Format, Args, Metadata) -> ok
371 log(Level, Fun, FunArgs, Metadata) -> ok
373 Types:
375 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 Create a log event at the given log level, with the given mes‐
385 sage to be logged and metadata. Examples:
386 %% 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 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 %% 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 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
420 add_handler(HandlerId, Module, Config) -> ok | {error, term()}
421 Types:
423 HandlerId = handler_id()
425 Module = module()
426 Config = handler_config()
427 Add a handler with the given configuration.
429 HandlerId is a unique identifier which must be used in all sub‐
431 sequent calls referring to this handler.
432 add_handler_filter(HandlerId, FilterId, Filter) ->
434 ok | {error, term()}
435 Types:
437 HandlerId = handler_id()
439 FilterId = filter_id()
440 Filter = filter()
441 Add a filter to the specified handler.
443 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 The return value of the fun specifies if a log event is to be
448 discarded or forwarded to the handler callback:
449 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 stop:
456 The filter did not pass, and the log event is immediately
457 discarded.
458 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 See section Filters in the User's Guide for more information
467 about filters.
468 Some built-in filters exist. These are defined in logger_fil‐
470 ters(3).
471 add_handlers(Application) -> ok | {error, term()}
473 Types:
475 Application = atom()
477 Reads the application configuration parameter logger and calls
479 add_handlers/1 with its contents.
480 add_handlers(HandlerConfig) -> ok | {error, term()}
482 Types:
484 HandlerConfig = [config_handler()]
486 config_handler() =
487 {handler, handler_id(), module(), handler_config()}
488 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 -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 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 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 [{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 add_primary_filter(FilterId, Filter) -> ok | {error, term()}
526 Types:
528 FilterId = filter_id()
530 Filter = filter()
531 Add a primary filter to Logger.
533 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 The return value of the fun specifies if a log event is to be
538 discarded or forwarded to the handlers:
539 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 stop:
547 The filter did not pass, and the log event is immediately
548 discarded.
549 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 See section Filters in the User's Guide for more information
558 about filters.
559 Some built-in filters exist. These are defined in logger_fil‐
561 ters(3).
562 get_config() ->
564 #{primary => primary_config(),
565 handlers => [handler_config()],
566 proxy => olp_config(),
567 module_levels =>
568 [{module(), level() | all | none}]}
569 Look up all current Logger configuration, including primary,
571 handler, and proxy configuration, and module level settings.
572 get_handler_config() -> [Config]
574 Types:
576 Config = handler_config()
578 Look up the current configuration for all handlers.
580 get_handler_config(HandlerId) -> {ok, Config} | {error, term()}
582 Types:
584 HandlerId = handler_id()
586 Config = handler_config()
587 Look up the current configuration for the given handler.
589 get_handler_ids() -> [HandlerId]
591 Types:
593 HandlerId = handler_id()
595 Look up the identities for all installed handlers.
597 get_primary_config() -> Config
599 Types:
601 Config = primary_config()
603 Look up the current primary configuration for Logger.
605 get_proxy_config() -> Config
607 Types:
609 Config = olp_config()
611 Look up the current configuration for the Logger proxy.
613 For more information about the proxy, see section Logger Proxy
615 in the Kernel User's Guide.
616 get_module_level() -> [{Module, Level}]
618 Types:
620 Module = module()
622 Level = level() | all | none
623 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 get_module_level(Modules) -> [{Module, Level}]
629 Types:
631 Modules = [Module] | Module
633 Module = module()
634 Level = level() | all | none
635 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 get_process_metadata() -> Meta | undefined
642 Types:
644 Meta = metadata()
646 Retrieve data set with set_process_metadata/1 or up‐
648 date_process_metadata/1.
649 i() -> ok
651 i(What) -> ok
653 Types:
655 What = primary | handlers | proxy | modules | handler_id()
657 Pretty print the Logger configuration.
659 remove_handler(HandlerId) -> ok | {error, term()}
661 Types:
663 HandlerId = handler_id()
665 Remove the handler identified by HandlerId.
667 remove_handler_filter(HandlerId, FilterId) -> ok | {error, term()}
669 Types:
671 HandlerId = handler_id()
673 FilterId = filter_id()
674 Remove the filter identified by FilterId from the handler iden‐
676 tified by HandlerId.
677 remove_primary_filter(FilterId) -> ok | {error, term()}
679 Types:
681 FilterId = filter_id()
683 Remove the primary filter identified by FilterId from Logger.
685 set_application_level(Application, Level) ->
687 ok | {error, not_loaded}
688 Types:
690 Application = atom()
692 Level = level() | all | none
693 Set the log level for all the modules of the specified applica‐
695 tion.
696 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 set_handler_config(HandlerId, Config) -> ok | {error, term()}
702 Types:
704 HandlerId = handler_id()
706 Config = handler_config()
707 Set configuration data for the specified handler. This over‐
709 writes the current handler configuration.
710 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 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 set_handler_config(HandlerId, Key :: level, Level) -> Return
722 set_handler_config(HandlerId,
724 Key :: filter_default,
725 FilterDefault) ->
726 Return
727 set_handler_config(HandlerId, Key :: filters, Filters) -> Return
729 set_handler_config(HandlerId, Key :: formatter, Formatter) ->
731 Return
732 set_handler_config(HandlerId, Key :: config, Config) -> Return
734 Types:
736 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 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 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 See the definition of the handler_config() type for more infor‐
758 mation about the different parameters.
759 set_primary_config(Config) -> ok | {error, term()}
761 Types:
763 Config = primary_config()
765 Set primary configuration data for Logger. This overwrites the
767 current configuration.
768 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 If a key is removed compared to the current configuration, the
775 default value is used.
776 set_primary_config(Key :: level, Level) -> ok | {error, term()}
778 set_primary_config(Key :: filter_default, FilterDefault) ->
780 ok | {error, term()}
781 set_primary_config(Key :: filters, Filters) ->
783 ok | {error, term()}
784 set_primary_config(Key :: metadata, Meta) -> ok | {error, term()}
786 Types:
788 Level = level() | all | none
790 FilterDefault = log | stop
791 Filters = [{filter_id(), filter()}]
792 Meta = metadata()
793 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 set_proxy_config(Config) -> ok | {error, term()}
799 Types:
801 Config = olp_config()
803 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 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 For more information about the proxy, see section Logger Proxy
814 in the Kernel User's Guide.
815 set_module_level(Modules, Level) -> ok | {error, term()}
817 Types:
819 Modules = [module()] | module()
821 Level = level() | all | none
822 Set the log level for the specified modules.
824 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 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 With this configuration, no debug messages will be logged, since
835 they are all stopped by the primary log level.
836 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 Debug events from other modules are still not logged.
842 To change the primary log level for Logger, use set_primary_con‐
844 fig(level, Level).
845 To change the log level for a handler, use set_handler_con‐
847 fig(HandlerId, level, Level).
848 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 set_process_metadata(Meta) -> ok
860 Types:
862 Meta = metadata()
864 Set metadata which Logger shall automatically insert in all log
866 events produced on the current process.
867 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 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 unset_application_level(Application) ->
880 ok | {error, {not_loaded, Application}}
881 Types:
883 Application = atom()
885 Unset the log level for all the modules of the specified appli‐
887 cation.
888 This function is a utility function that calls logger:unset_mod‐
890 ule_level/2 for each module associated with an application.
891 unset_module_level() -> ok
893 Remove module specific log settings. After this, the primary log
895 level is used for all modules.
896 unset_module_level(Modules) -> ok
898 Types:
900 Modules = [module()] | module()
902 Remove module specific log settings. After this, the primary log
904 level is used for the specified modules.
905 unset_process_metadata() -> ok
907 Delete data set with set_process_metadata/1 or up‐
909 date_process_metadata/1.
910 update_formatter_config(HandlerId, FormatterConfig) ->
912 ok | {error, term()}
913 Types:
915 HandlerId = handler_id()
917 FormatterConfig = formatter_config()
918 Update the formatter configuration for the specified handler.
920 The new configuration is merged with the existing formatter con‐
922 figuration.
923 To overwrite the existing configuration without any merge, use
925 set_handler_config(HandlerId, formatter, {FormatterModule, FormatterConfig}).
927 update_formatter_config(HandlerId, Key, Value) ->
929 ok | {error, term()}
930 Types:
932 HandlerId = handler_id()
934 Key = atom()
935 Value = term()
936 Update the formatter configuration for the specified handler.
938 This is equivalent to
940 update_formatter_config(HandlerId, #{Key => Value})
942 update_handler_config(HandlerId, Config) -> ok | {error, term()}
944 Types:
946 HandlerId = handler_id()
948 Config = handler_config()
949 Update configuration data for the specified handler. This func‐
951 tion behaves as if it was implemented as follows:
952 {ok, {_, Old}} = logger:get_handler_config(HandlerId),
954 logger:set_handler_config(HandlerId, maps:merge(Old, Config)).
955 To overwrite the existing configuration without any merge, use
958 set_handler_config/2.
959 update_handler_config(HandlerId, Key :: level, Level) -> Return
961 update_handler_config(HandlerId,
963 Key :: filter_default,
964 FilterDefault) ->
965 Return
966 update_handler_config(HandlerId, Key :: filters, Filters) ->
968 Return
969 update_handler_config(HandlerId, Key :: formatter, Formatter) ->
971 Return
972 update_handler_config(HandlerId, Key :: config, Config) -> Return
974 Types:
976 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 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 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 See the definition of the handler_config() type for more infor‐
998 mation about the different parameters.
999 update_primary_config(Config) -> ok | {error, term()}
1001 Types:
1003 Config = primary_config()
1005 Update primary configuration data for Logger. This function be‐
1007 haves as if it was implemented as follows:
1008 Old = logger:get_primary_config(),
1010 logger:set_primary_config(maps:merge(Old, Config)).
1011 To overwrite the existing configuration without any merge, use
1014 set_primary_config/1.
1015 update_process_metadata(Meta) -> ok
1017 Types:
1019 Meta = metadata()
1021 Set or update metadata to use when logging from current process
1023 If process metadata exists for the current process, this func‐
1025 tion behaves as if it was implemented as follows:
1026 logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
1028 If no process metadata exists, the function behaves as
1031 set_process_metadata/1.
1032 update_proxy_config(Config) -> ok | {error, term()}
1034 Types:
1036 Config = olp_config()
1038 Update configuration data for the Logger proxy. This function
1040 behaves as if it was implemented as follows:
1041 Old = logger:get_proxy_config(),
1043 logger:set_proxy_config(maps:merge(Old, Config)).
1044 To overwrite the existing configuration without any merge, use
1047 set_proxy_config/1.
1048 For more information about the proxy, see section Logger Proxy
1050 in the Kernel User's Guide.
1051
1054 compare_levels(Level1, Level2) -> eq | gt | lt
1055 Types:
1057 Level1 = Level2 = level() | all | none
1059 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 format_report(Report) -> FormatArgs
1065 Types:
1067 Report = report()
1069 FormatArgs = {io:format(), [term()]}
1070 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 The function produces lines of Key: Value from key-value lists.
1078 Strings are printed with ~ts and other terms with ~tp.
1079 If Report is a map, it is converted to a key-value list before
1081 formatting as such.
1082 timestamp() -> timestamp()
1084 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 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 reconfigure() -> ok | {error, term()}
1095 Reconfigure Logger using updated kernel configuration that was
1097 set after kernel application was loaded.
1098 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
1104 The following functions are to be exported from a handler callback mod‐
1105 ule.
1106
1108 HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason}
1109 Types:
1111 Config1 = Config2 = handler_config()
1113 Reason = term()
1114 This callback function is optional.
1116 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 The handler identity is associated with the id key in Config1.
1122 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 If the configuration is faulty, or if the initiation fails, the
1128 callback function must return {error,Reason}.
1129 HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Con‐
1131 fig} | {error, Reason}
1132 Types:
1134 SetOrUpdate = set | update
1136 OldConfig = NewConfig = Config = handler_config()
1137 Reason = term()
1138 This callback function is optional.
1140 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 OldConfig is the existing configuration and NewConfig is the new
1146 configuration.
1147 The handler identity is associated with the id key in OldConfig.
1149 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 If everything succeeds, the callback function must return a pos‐
1160 sibly adjusted configuration in {ok,Config}.
1161 If the configuration is faulty, the callback function must re‐
1163 turn {error,Reason}.
1164 HModule:filter_config(Config) -> FilteredConfig
1166 Types:
1168 Config = FilteredConfig = handler_config()
1170 This callback function is optional.
1172 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 It allows the handler to remove internal data fields from its
1178 configuration data before it is returned to the caller.
1179 HModule:log(LogEvent, Config) -> void()
1181 Types:
1183 LogEvent = log_event()
1185 Config = handler_config()
1186 This callback function is mandatory.
1188 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 The handler identity is associated with the id key in Config.
1195 The handler must log the event.
1197 The return value from this function is ignored by Logger.
1199 HModule:removing_handler(Config) -> ok
1201 Types:
1203 Config = handler_config()
1205 This callback function is optional.
1207 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 The handler identity is associated with the id key in Config.
1213 The return value is ignored by Logger.
1215
1217 The following functions are to be exported from a formatter callback
1218 module.
1219
1221 FModule:check_config(FConfig) -> ok | {error, Reason}
1222 Types:
1224 FConfig = formatter_config()
1226 Reason = term()
1227 This callback function is optional.
1229 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 The following Logger API functions can trigger this callback:
1236 * logger:add_handler/3
1238 * logger:set_handler_config/2,3
1240 * logger:update_handler_config/2,3
1242 * logger:update_formatter_config/2
1244 See logger_formatter(3) for an example implementation. log‐
1246 ger_formatter is the default formatter used by Logger.
1247 FModule:format(LogEvent, FConfig) -> FormattedLogEntry
1249 Types:
1251 LogEvent = log_event()
1253 FConfig = formatter_config()
1254 FormattedLogEntry = unicode:chardata()
1255 This callback function is mandatory.
1257 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 See logger_formatter(3) for an example implementation. log‐
1264 ger_formatter is the default formatter used by Logger.
1265
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)
1269Ericsson AB kernel 8.3.2 logger(3)