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 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 up‐
171 date_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 di‐
190 rectly to a string. See the type definition of report_cb(),
191 and section Log Message in the User's Guide for more infor‐
192 mation 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 ap‐
403 plied. 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(3).
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 ap‐
493 plied. 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(3).
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 up‐
599 date_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 be‐
665 fore 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 de‐
705 fault values. To update only specified data, and keep the exist‐
706 ing configuration for the rest, use update_handler_config/3.
707 See the definition of the handler_config() type for more infor‐
709 mation about the different parameters.
710 set_primary_config(Config) -> ok | {error, term()}
712 Types:
714 Config = primary_config()
716 Set primary configuration data for Logger. This overwrites the
718 current configuration.
719 To modify the existing configuration, use update_primary_con‐
721 fig/1, or, if a more complex merge is needed, read the current
722 configuration with get_primary_config/0, then do the merge be‐
723 fore writing the new configuration back with this function.
724 If a key is removed compared to the current configuration, the
726 default value is used.
727 set_primary_config(Key :: level, Level) -> ok | {error, term()}
729 set_primary_config(Key :: filter_default, FilterDefault) ->
731 ok | {error, term()}
732 set_primary_config(Key :: filters, Filters) ->
734 ok | {error, term()}
735 Types:
737 Level = level() | all | none
739 FilterDefault = log | stop
740 Filters = [{filter_id(), filter()}]
741 Add or update primary configuration data for Logger. If the
743 given Key already exists, its associated value will be changed
744 to the given value. If it does not exist, it will be added.
745 set_proxy_config(Config) -> ok | {error, term()}
747 Types:
749 Config = olp_config()
751 Set configuration data for the Logger proxy. This overwrites the
753 current proxy configuration. Keys that are not specified in the
754 Config map gets default values.
755 To modify the existing configuration, use update_proxy_config/1,
757 or, if a more complex merge is needed, read the current configu‐
758 ration with get_proxy_config/0, then do the merge before writing
759 the new configuration back with this function.
760 For more information about the proxy, see section Logger Proxy
762 in the Kernel User's Guide.
763 set_module_level(Modules, Level) -> ok | {error, term()}
765 Types:
767 Modules = [module()] | module()
769 Level = level() | all | none
770 Set the log level for the specified modules.
772 The log level for a module overrides the primary log level of
774 Logger for log events originating from the module in question.
775 Notice, however, that it does not override the level configura‐
776 tion for any handler.
777 For example: Assume that the primary log level for Logger is
779 info, and there is one handler, h1, with level info and one han‐
780 dler, h2, with level debug.
781 With this configuration, no debug messages will be logged, since
783 they are all stopped by the primary log level.
784 If the level for mymodule is now set to debug, then debug events
786 from this module will be logged by the handler h2, but not by
787 handler h1.
788 Debug events from other modules are still not logged.
790 To change the primary log level for Logger, use set_primary_con‐
792 fig(level, Level).
793 To change the log level for a handler, use set_handler_con‐
795 fig(HandlerId, level, Level).
796 Note:
798 The originating module for a log event is only detected if the
799 key mfa exists in the metadata, and is associated with {Module,
800 Function, Arity}. When log macros are used, this association is
801 automatically added to all log events. If an API function is
802 called directly, without using a macro, the logging client must
803 explicitly add this information if module levels shall have any
804 effect.
805 set_process_metadata(Meta) -> ok
808 Types:
810 Meta = metadata()
812 Set metadata which Logger shall automatically insert in all log
814 events produced on the current process.
815 Location data produced by the log macros, and/or metadata given
817 as argument to the log call (API function or macro), are merged
818 with the process metadata. If the same keys occur, values from
819 the metadata argument to the log call overwrite values from the
820 process metadata, which in turn overwrite values from the loca‐
821 tion data.
822 Subsequent calls to this function overwrites previous data set.
824 To update existing data instead of overwriting it, see up‐
825 date_process_metadata/1.
826 unset_application_level(Application) ->
828 ok | {error, {not_loaded, Application}}
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 utility function that calls logger:unset_mod‐
838 ule_level/2 for each module associated with an application.
839 unset_module_level() -> ok
841 Remove module specific log settings. After this, the primary log
843 level is used for all modules.
844 unset_module_level(Modules) -> ok
846 Types:
848 Modules = [module()] | module()
850 Remove module specific log settings. After this, the primary log
852 level is used for the specified modules.
853 unset_process_metadata() -> ok
855 Delete data set with set_process_metadata/1 or up‐
857 date_process_metadata/1.
858 update_formatter_config(HandlerId, FormatterConfig) ->
860 ok | {error, term()}
861 Types:
863 HandlerId = handler_id()
865 FormatterConfig = formatter_config()
866 Update the formatter configuration for the specified handler.
868 The new configuration is merged with the existing formatter con‐
870 figuration.
871 To overwrite the existing configuration without any merge, use
873 set_handler_config(HandlerId, formatter, {FormatterModule, FormatterConfig}).
875 update_formatter_config(HandlerId, Key, Value) ->
877 ok | {error, term()}
878 Types:
880 HandlerId = handler_id()
882 Key = atom()
883 Value = term()
884 Update the formatter configuration for the specified handler.
886 This is equivalent to
888 update_formatter_config(HandlerId, #{Key => Value})
890 update_handler_config(HandlerId, Config) -> ok | {error, term()}
892 Types:
894 HandlerId = handler_id()
896 Config = handler_config()
897 Update configuration data for the specified handler. This func‐
899 tion behaves as if it was implemented as follows:
900 {ok, {_, Old}} = logger:get_handler_config(HandlerId),
902 logger:set_handler_config(HandlerId, maps:merge(Old, Config)).
903 To overwrite the existing configuration without any merge, use
906 set_handler_config/2.
907 update_handler_config(HandlerId, Key :: level, Level) -> Return
909 update_handler_config(HandlerId,
911 Key :: filter_default,
912 FilterDefault) ->
913 Return
914 update_handler_config(HandlerId, Key :: filters, Filters) ->
916 Return
917 update_handler_config(HandlerId, Key :: formatter, Formatter) ->
919 Return
920 update_handler_config(HandlerId, Key :: config, Config) -> Return
922 Types:
924 HandlerId = handler_id()
926 Level = level() | all | none
927 FilterDefault = log | stop
928 Filters = [{filter_id(), filter()}]
929 Formatter = {module(), formatter_config()}
930 Config = term()
931 Return = ok | {error, term()}
932 Add or update configuration data for the specified handler. If
934 the given Key already exists, its associated value will be
935 changed to the given value. If it does not exist, it will be
936 added.
937 If the value is incomplete, which for example can be the case
939 for the config key, it is up to the handler implementation how
940 the unspecified parts are set. For all handlers in the Kernel
941 application, unspecified data for the config key is not changed.
942 To reset unspecified data to default values, use set_han‐
943 dler_config/3.
944 See the definition of the handler_config() type for more infor‐
946 mation about the different parameters.
947 update_primary_config(Config) -> ok | {error, term()}
949 Types:
951 Config = primary_config()
953 Update primary configuration data for Logger. This function be‐
955 haves as if it was implemented as follows:
956 Old = logger:get_primary_config(),
958 logger:set_primary_config(maps:merge(Old, Config)).
959 To overwrite the existing configuration without any merge, use
962 set_primary_config/1.
963 update_process_metadata(Meta) -> ok
965 Types:
967 Meta = metadata()
969 Set or update metadata to use when logging from current process
971 If process metadata exists for the current process, this func‐
973 tion behaves as if it was implemented as follows:
974 logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)).
976 If no process metadata exists, the function behaves as
979 set_process_metadata/1.
980 update_proxy_config(Config) -> ok | {error, term()}
982 Types:
984 Config = olp_config()
986 Update configuration data for the Logger proxy. This function
988 behaves as if it was implemented as follows:
989 Old = logger:get_proxy_config(),
991 logger:set_proxy_config(maps:merge(Old, Config)).
992 To overwrite the existing configuration without any merge, use
995 set_proxy_config/1.
996 For more information about the proxy, see section Logger Proxy
998 in the Kernel User's Guide.
999
1002 compare_levels(Level1, Level2) -> eq | gt | lt
1003 Types:
1005 Level1 = Level2 = level() | all | none
1007 Compare the severity of two log levels. Returns gt if Level1 is
1009 more severe than Level2, lt if Level1 is less severe, and eq if
1010 the levels are equal.
1011 format_report(Report) -> FormatArgs
1013 Types:
1015 Report = report()
1017 FormatArgs = {io:format(), [term()]}
1018 Convert a log message on report form to {Format, Args}. This is
1020 the default report callback used by logger_formatter(3) when no
1021 custom report callback is found. See section Log Message in the
1022 Kernel User's Guide for information about report callbacks and
1023 valid forms of log messages.
1024 The function produces lines of Key: Value from key-value lists.
1026 Strings are printed with ~ts and other terms with ~tp.
1027 If Report is a map, it is converted to a key-value list before
1029 formatting as such.
1030 timestamp() -> timestamp()
1032 Return a timestamp that can be inserted as the time field in the
1034 meta data for a log event. It is produced with os:sys‐
1035 tem_time(microsecond).
1036 Notice that Logger automatically inserts a timestamp in the meta
1038 data unless it already exists. This function is exported for the
1039 rare case when the timestamp must be taken at a different point
1040 in time than when the log event is issued.
1041
1043 The following functions are to be exported from a handler callback mod‐
1044 ule.
1045
1047 HModule:adding_handler(Config1) -> {ok, Config2} | {error, Reason}
1048 Types:
1050 Config1 = Config2 = handler_config()
1052 Reason = term()
1053 This callback function is optional.
1055 The function is called on a temporary process when a new handler
1057 is about to be added. The purpose is to verify the configuration
1058 and initiate all resources needed by the handler.
1059 The handler identity is associated with the id key in Config1.
1061 If everything succeeds, the callback function can add possible
1063 default values or internal state values to the configuration,
1064 and return the adjusted map in {ok,Config2}.
1065 If the configuration is faulty, or if the initiation fails, the
1067 callback function must return {error,Reason}.
1068 HModule:changing_config(SetOrUpdate, OldConfig, NewConfig) -> {ok, Con‐
1070 fig} | {error, Reason}
1071 Types:
1073 SetOrUpdate = set | update
1075 OldConfig = NewConfig = Config = handler_config()
1076 Reason = term()
1077 This callback function is optional.
1079 The function is called on a temporary process when the configu‐
1081 ration for a handler is about to change. The purpose is to ver‐
1082 ify and act on the new configuration.
1083 OldConfig is the existing configuration and NewConfig is the new
1085 configuration.
1086 The handler identity is associated with the id key in OldConfig.
1088 SetOrUpdate has the value set if the configuration change origi‐
1090 nates from a call to set_handler_config/2,3, and update if it
1091 originates from update_handler_config/2,3. The handler can use
1092 this parameter to decide how to update the value of the config
1093 field, that is, the handler specific configuration data. Typi‐
1094 cally, if SetOrUpdate equals set, values that are not specified
1095 must be given their default values. If SetOrUpdate equals up‐
1096 date, the values found in OldConfig must be used instead.
1097 If everything succeeds, the callback function must return a pos‐
1099 sibly adjusted configuration in {ok,Config}.
1100 If the configuration is faulty, the callback function must re‐
1102 turn {error,Reason}.
1103 HModule:filter_config(Config) -> FilteredConfig
1105 Types:
1107 Config = FilteredConfig = handler_config()
1109 This callback function is optional.
1111 The function is called when one of the Logger API functions for
1113 fetching the handler configuration is called, for example log‐
1114 ger:get_handler_config/1.
1115 It allows the handler to remove internal data fields from its
1117 configuration data before it is returned to the caller.
1118 HModule:log(LogEvent, Config) -> void()
1120 Types:
1122 LogEvent = log_event()
1124 Config = handler_config()
1125 This callback function is mandatory.
1127 The function is called when all primary filters and all handler
1129 filters for the handler in question have passed for the given
1130 log event. It is called on the client process, that is, the
1131 process that issued the log event.
1132 The handler identity is associated with the id key in Config.
1134 The handler must log the event.
1136 The return value from this function is ignored by Logger.
1138 HModule:removing_handler(Config) -> ok
1140 Types:
1142 Config = handler_config()
1144 This callback function is optional.
1146 The function is called on a temporary process when a handler is
1148 about to be removed. The purpose is to release all resources
1149 used by the handler.
1150 The handler identity is associated with the id key in Config.
1152 The return value is ignored by Logger.
1154
1156 The following functions are to be exported from a formatter callback
1157 module.
1158
1160 FModule:check_config(FConfig) -> ok | {error, Reason}
1161 Types:
1163 FConfig = formatter_config()
1165 Reason = term()
1166 This callback function is optional.
1168 The function is called by a Logger when formatter configuration
1170 is set or modified. The formatter must validate the given con‐
1171 figuration and return ok if it is correct, and {error,Reason} if
1172 it is faulty.
1173 The following Logger API functions can trigger this callback:
1175 * logger:add_handler/3
1177 * logger:set_handler_config/2,3
1179 * logger:update_handler_config/2,3
1181 * logger:update_formatter_config/2
1183 See logger_formatter(3) for an example implementation. log‐
1185 ger_formatter is the default formatter used by Logger.
1186 FModule:format(LogEvent, FConfig) -> FormattedLogEntry
1188 Types:
1190 LogEvent = log_event()
1192 FConfig = formatter_config()
1193 FormattedLogEntry = unicode:chardata()
1194 This callback function is mandatory.
1196 The function can be called by a log handler to convert a log
1198 event term to a printable string. The returned value can, for
1199 example, be printed as a log entry to the console or a file us‐
1200 ing io:put_chars/1,2.
1201 See logger_formatter(3) for an example implementation. log‐
1203 ger_formatter is the default formatter used by Logger.
1204
1206 config(4), erlang(3), io(3), logger_disk_log_h(3), logger_filters(3),
1207 logger_formatter(3), logger_std_h(3), unicode(3)
1208Ericsson AB kernel 7.3.1.1 logger(3)