Overview

Module logi

• Description
• Data Types
• Function Index
• Function Details

Copyright © 2014-2016 Takeru Ohta <phjgt308@gmail.com>

Description

Logger Interface

This module mainly provides logger related functions. A logger has own headers, metadata, filter and can issue log messages to a destination channel.

EXAMPLE

  > error_logger:tty(false). % Suppresses annoying warnings for the sake of brevity
  > {ok, _} = logi_channel:install_sink(logi_builtin_sink_io_device:new(foo), info). % Installs a sink to the default channel
  > logi:info("hello world").
  2015-11-09 08:18:34.954 [info] nonode@nohost <0.91.0> erl_eval:do_apply:673 [] hello world
  

Data Types

context()

context() = logger_instance()

This is provided only for maintaining compatibility with v0.0.12

context_ref()

context_ref() = logger()

This is provided only for maintaining compatibility with v0.0.12

frequency_policy()

frequency_policy() = always | once | {once_in_times, Times::pos_integer()} | {interval, MilliSeconds::non_neg_integer()}

headers()

headers() = #{}

The headers of a log message.

log_option()

log_option() = {logger, logger()} | {location, logi_location:location()} | {headers, headers()} | {metadata, metadata()} | {timestamp, erlang:timestamp()} | {frequency, frequency_policy()}

log_options()

log_options() = [log_option()]

logger()

logger() = logger_id() | logger_instance()

A logger

logger_id()

logger_id() = atom()

The ID of a saved logger instance (see: save/2).

logger_instance()

abstract datatype: logger_instance()

A logger instance

logger_map_form()

logger_map_form() = #{channel => logi_channel:id(), headers => headers(), metadata => metadata(), filter => logi_filter:filter(), next => logger_instance()}

The map representation of a logger.

metadata()

metadata() = #{}

The metadata of a log message

new_option()

new_option() = {channel, logi_channel:id()} | {headers, headers()} | {metadata, metadata()} | {filter, logi_filter:filter()} | {next, logger_instance()}

[channel] - The destination channel - The log messages issued by the created logger will (logically) send to the channel - Default: logi_channel:default_channel()

[headers] - The headers of the created logger - Default: #{}

[metadata] - The metadata of the created logger - Default: #{}

[filter] - A log message filter - Default: none (optional)

new_options()

new_options() = [new_option()]

severity()

severity() = debug | info | notice | warning | error | critical | alert | emergency

Severity of a log message

Function Index

Function Details

alert/1

Equivalent to alert(Format, []).

alert/2

Equivalent to alert(Format, Data, []).

alert/3

Equivalent to log(alert, Format, Data, Options).

critical/1

Equivalent to critical(Format, []).

critical/2

Equivalent to critical(Format, Data, []).

critical/3

Equivalent to log(critical, Format, Data, Options).

debug/1

Equivalent to debug(Format, []).

debug/2

Equivalent to debug(Format, Data, []).

debug/3

Equivalent to log(debug, Format, Data, Options).

debug_opt/3

Equivalent to debug(Format, Data, Options).

default_logger/0

Returns the default logger

delete_headers/1

Equivalent to delete_headers(Keys, []).

delete_headers/2

Deletes headers which associated with Keys

If the logger has nested loggers, the function is applied to them recursively.

OPTION

[logger] - The logger to which the operation applies. - Default: logi:default_logger().

  > Logger = logi:new([{headers, #{a => 1, b => 2}}]).
  > logi:to_map(logi:delete_headers([a], [{logger, Logger}])).
  #{channel => logi_default_log,headers => #{b => 2},metadata => #{}}
  

delete_metadata/1

Equivalent to delete_metadata(Keys, []).

delete_metadata/2

Deletes metadata entries which associated with Keys

If the logger has nested loggers, the function is applied to them recursively.

OPTION

[logger] - The logger to which the operation applies. - Default: logi:default_logger().

  > Logger = logi:new([{metadata, #{a => 1, b => 2}}]).
  > logi:to_map(logi:delete_metadata([a], [{logger, Logger}])).
  #{channel => logi_default_log,headers => #{},metadata => #{b => 2}}
  

emergency/1

Equivalent to emergency(Format, []).

emergency/2

Equivalent to emergency(Format, Data, []).

emergency/3

Equivalent to log(emergency, Format, Data, Options).

ensure_to_be_instance/1

Returns the logger instance associated to Logger

  > logi:ensure_to_be_instance(unsaved).
  {logi_logger,unsaved,#{},#{},undefined,undefined}
 
  > logi:save(saved, logi:new([{channel, hoge}])).
  > logi:ensure_to_be_instance(hoge).
  {logi_logger,hoge,#{},#{},undefined,undefined}
 
  > logi:ensure_to_be_instance(logi:new([{channel, instance}])).
  {logi_logger,instance,#{},#{},undefined,undefined}
  

erase/0

Returns the saved loggers and deletes them from the process dictionary.

  > logi:save(hoge, logi:new()).
  > logi:erase().
  [{hoge,{logi_logger,logi_default_log,#{},#{},undefined,undefined}}]
 
  > logi:erase().
  []
  

erase/1

Returns the logger associated with LoggerId and deletes it from the process dictionary.

Returns undefined if no logger is associated with LoggerId.

  > logi:save(hoge, logi:new()).
  > logi:erase(hoge).
  {logi_logger,logi_default_log,#{},#{},undefined,undefined}
 
  > logi:erase(hoge).
  undefined
  

error/1

Equivalent to error(Format, []).

error/2

Equivalent to error(Format, Data, []).

error/3

Equivalent to log(error, Format, Data, Options).

from_list/1

Aggregates Loggers into a logger instance

The head logger in Loggers becomes the root of the aggregation.

e.g. from_list([new(), new(), new()]) is equivalent to new([{next, new([{next, new()}])}]).

  > GetChannel = fun (Logger) -> maps:get(channel, logi:to_map(Logger)) end.
 
  > Logger0 = logi:new([{channel, aaa}]).
  > Logger1 = logi:new([{channel, bbb}]).
  > Logger2 = logi:new([{channel, ccc}, {next, logi:new([{channel, ccc_sub}])}]).
 
  > [aaa, bbb] = lists:map(GetChannel, logi:to_list(logi:from_list([Logger0, Logger1]))).
  > [ccc, ccc_sub, aaa, bbb] = lists:map(GetChannel, logi:to_list(logi:from_list([Logger2, Logger0, Logger1]))).
  

from_map/1

Creates a new logger instance from Map

Default Value: - channel: logi_channel:default_channel() - headers: #{} - metadata: #{} - filter: none (optional) - next: none (optional)

  > logi:to_map(logi:from_map(#{})).
  #{channel => logi_default_log,headers => #{},metadata => #{}}
  

info/1

Equivalent to info(Format, []).

info/2

Equivalent to info(Format, Data, []).

info/3

Equivalent to log(info, Format, Data, Options).

info_opt/3

Equivalent to info(Format, Data, Options).

is_logger/1

Returns true if X is a logger, otherwise false

is_severity/1

Returns true if X is a severity, otherwise false

load/1

Loads a logger which associated with the ID LoggerId from the process dictionary

  > error = logi:load(hoge_log).
 
  > logi:save(hoge_log, logi:new()).
  > {ok, _} = logi:load(hoge_log).
  

load_context/0

Equivalent to ensure_to_be_instance(default_logger()).

load_default/0

Equivalent to load(default_logger()).

log/4

Issues a log message to the destination channel.

If the logger has a filter, the message will be passed to it. And if the message has not been discarded by a filter, the logger will (logically) send it to the destination channel. Finally, the message will be consumed by the sinks which are installed to the channel. But the sinks which does not satisfy specified condition (i.e. logi_sink:condition/0) are ignored.

  > {ok, _} = logi_channel:install_sink(logi_builtin_sink_io_device:new(sample), info). % Installs a sink to the default channel
  > logi:log(debug, "hello world", [], []). % There are no applicable sinks (the severity is too low)
  > logi:log(info, "hello world", [], []). % The log message is consumed by the above sink
  2015-10-22 13:16:37.003 [info] nonode@nohost <0.91.0> erl_eval:do_apply:673 [] hello world
  

If the logger has nested loggers, the function is applied to them recursively.

  > {ok, _} = logi_channel:install_sink(logi_builtin_sink_io_device:new(sample), info). % Installs a sink to the default channel
  > Logger = logi:from_list([logi:new([{headers, #{id => hoge}}]), logi:new([{headers, #{id => fuga}}])]).
  > logi:log(info, "hello world", [], [{logger, Logger}]).
  2015-10-22 13:28:10.332 [info] nonode@nohost <0.91.0> erl_eval:do_apply:673 [id=hoge] hello world
  2015-10-22 13:28:10.332 [info] nonode@nohost <0.91.0> erl_eval:do_apply:673 [id=fuga] hello world
  

NOTE

Typically, it is preferred to log messages through the wrapper functions (i.e. logi:Severity/{1,2,3}) rather than calling the function directly.

If the {parse_transform, logi_transform} compiler option is specified, the invocation of the wrapper functions will be transformed to a more efficient code at compile time.

  %% Current location (Application, Module, Function and Line) is detected at compile time
  Location = logi_location:unsafe_new(self(), Application, Module, Function, Line),
  case logi:'_ready'(info, Location, Options) of
    {Logger, []}                    -> Logger;
    {Logger, ListOfContextAndSinks} -> logi:_write(ListOfContextAndSinks, Format, Data)
  end.
  

From the efficiency point of view, the following two points are important: - 1. An implicit call of logi_location:guess_location/0 to guess the currrent location is replaced by the more efficient and accurate code - 2. If it is unnecessary (e.g. there are no applicable sinks), Format and Data will not be evaluated

See also: logi_location:guess_location/0.

make_context/0

Equivalent to new().

make_context/1

Equivalent to new([{channel, ChannelId}]).

new/0

Equivalent to new([]).

new/1

Creates a new logger instance

notice/1

Equivalent to notice(Format, []).

notice/2

Equivalent to notice(Format, Data, []).

notice/3

Equivalent to log(notice, Format, Data, Options).

notice_opt/3

Equivalent to notice(Format, Data, Options).

save/2

Saves Logger with the ID LoggerId to the process dictionary

If LoggerId already exists, the old logger instance is deleted and replaced by Logger and the function returns the old instance. Otherwise it returns undefined.

  > Logger = logi:new().
  > logi:save(sample_log, Logger).
 
  % The following two expression is equivalent.
  > logi:info("hello world", [{logger, Logger}]).  % referred by instance
  > logi:info("hello world", [{logger, sample_log}]). % referred by ID
  

save_as_default/1

Equivalent to save(default_logger(), Logger).

save_context/1

Equivalent to save_as_default(Logger).

set_headers/1

Equivalent to set_headers(Headers, []).

set_headers/2

Sets headers of the logger

If the logger has nested loggers, the function is applied to them recursively.

OPTION

[logger] - The logger to which the operation applies. - Default: logi:default_logger().

[if_exists] - If the value is supersede, the existing headers are deleted and replaced by Headers. - If the value is overwrite, the existing headers and Headers are merged and the rear has priority when a key collision occurs. - If the value is ignore, the existing headers and Headers are merged and the former has priority when a key collision occurs. - Default: overwrite

  > Logger = logi:new([{headers, #{a => 10, b => 20}}]).
  > Set = fun (Headers, IfExists) ->
              L = logi:set_headers(Headers, [{logger, Logger}, {if_exists, IfExists}]),
              maps:get(headers, logi:to_map(L))
          end.
 
  > true = #{a => 0,           c => 30} =:= Set(#{a => 0, c => 30}, supersede).
  > true = #{a => 0,  b => 20, c => 30} =:= Set(#{a => 0, c => 30}, overwrite).
  > true = #{a => 10, b => 20, c => 30} =:= Set(#{a => 0, c => 30}, ignore).
  

set_metadata/1

Equivalent to set_metadata(Metadata, []).

set_metadata/2

Sets metadata of the logger

If the logger has nested loggers, the function is applied to them recursively.

OPTION

[logger] - The logger to which the operation applies. - Default: logi:default_logger().

[if_exists] - If the value is supersede, the existing metadata is deleted and replaced by Metadata. - If the value is overwrite, the existing metadata and Metadata are merged and the rear has priority when a key collision occurs. - If the value is ignore, the existing metadata and Metadata are merged and the former has priority when a key collision occurs. - Default: overwrite

  > Logger = logi:new([{metadata, #{a => 10, b => 20}}]).
  > Set = fun (Metadata, IfExists) ->
              L = logi:set_metadata(Metadata, [{logger, Logger}, {if_exists, IfExists}]),
              maps:get(metadata, logi:to_map(L))
          end.
 
  > true = #{a => 0,           c => 30} =:= Set(#{a => 0, c => 30}, supersede).
  > true = #{a => 0,  b => 20, c => 30} =:= Set(#{a => 0, c => 30}, overwrite).
  > true = #{a => 10, b => 20, c => 30} =:= Set(#{a => 0, c => 30}, ignore).
  

severities/0

Returns the available severity list

severity_level/1

Returns the level of Severity

to_list/1

Flattens the nested logger

The nested loggers are collected as a flat list. The next fields of the resulting loggers are removed.

  > Logger0 = logi:new().
  > Logger1 = logi:new([{next, Logger0}]).
  > Logger2 = logi:new([{next, Logger1}]).
  > [Logger0] = logi:to_list(Logger0).
  > [Logger0, Logger0] = logi:to_list(Logger1).
  > [Logger0, Logger0, Logger0] = logi:to_list(Logger2).
  

to_map/1

Converts Logger into a map form

The optional entries (i.e. filter and next) will be omitted from the resulting map if the value is not set.

  > logi:to_map(logi:new()).
  #{channel => logi_default_log,headers => #{},metadata => #{}}
 
  > logi:to_map(logi:new([{next, logi:new()}])).
  #{channel => logi_default_log,
    headers => #{},
    metadata => #{},
    next => {logi_logger,logi_default_log,#{},#{},undefined,undefined}}
  

verbose/1

Equivalent to verbose(Format, []).

verbose/2

Equivalent to verbose(Format, Data, []).

verbose/3

Equivalent to log(debug, Format, Data, Options).

verbose_opt/3

Equivalent to debug(Format, Data, Options).

warning/1

Equivalent to warning(Format, []).

warning/2

Equivalent to warning(Format, Data, []).

warning/3

Equivalent to log(warning, Format, Data, Options).

warning_opt/3

Equivalent to warning(Format, Data, Options).

which_loggers/0

Returns the ID list of the saved loggers

  > logi:save(hoge, logi:new()).
  > logi:which_loggers().
  [hoge]
  

Overview

Generated by EDoc