Module logi_channel

Description
Data Types
Function Index
Function Details

Log Message Channels.

Behaviours: gen_server.

Description

Log Message Channels

A channel (logically) receives log messages from loggers and delivers the messages to installed sinks.

EXAMPLE

Basic usage:

  > error_logger:tty(false). % Suppresses annoying warning outputs for brevity
 
  %%
  %% CREATE CHANNEL
  %%
  > ok = logi_channel:create(sample_log).
  > logi_channel:which_channels().
  [sample_log,logi_default_log]  % 'logi_default_log' is created automatically when 'logi' application was started
 
  %%
  %% INSTALL SINK
  %%
  > WriteFun = fun (_, Format, Data) -> io:format("[my_sink] " ++ Format ++ "\n", Data) end.
  > Sink = logi_builtin_sink_fun:new(sample_sink, WriteFun).
  > {ok, _} = logi_channel:install_sink(sample_log, Sink, info). % Installs Sink with info level
  > logi_channel:which_sinks(sample_log).
  [sample_sink]
 
  %%
  %% OUTPUT LOG MESSAGE
  %%
  > logi:debug("hello world", [], [{logger, sample_log}]).
  % The message is not emitted (the severity is too low).
 
  > logi:info("hello world", [], [{logger, sample_log}]).
  [my_sink] hello world
 
  > logi:alert("hello world", [], [{logger, sample_log}]).
  [my_sink] hello world
 
  > logi:info("hello world"). % If logger option is omitted, the default channel will be used
  % The message is not emitted (no sinks are installed to the default channel).

Data Types

id()

id() = atom()

The identifier of a channel

install_sink_option()

install_sink_option() = {if_exists, error | ignore | supersede}

if_exists: - The confliction handling policy. - If a sink with the same identifier already exists, - error: the function returns an error {error, {already_installed, ExistingSink}}. - ignore: the new sink is ignored. Then the function returns {ok, ExistingSink}. - supersede: the new sink supersedes it. Then the function returns {ok, OldSink}. - default: supersede

install_sink_options()

install_sink_options() = [install_sink_option()]

installed_sink()

installed_sink() = #{sink => logi_sink:sink(), condition => logi_condition:condition(), sink_sup => logi_sink_proc:sink_sup(), writer => logi_sink_writer:writer() | undefined}

The information of an installed sink

Function Index

create/1	Creates a new channel.
default_channel/0	The default channel.
delete/1	Deletes a channel.
find_sink/1	Equivalent to `find_sink(default_channel(), SinkId)`.
find_sink/2	Searchs for `SinkId` in `Channel`
install_sink/2	Equivalent to `install_sink(default_channel(), Sink, Condition)`.
install_sink/3	Equivalent to `install_sink_opt(Channel, Sink, Condition, [])`.
install_sink_opt/3	Equivalent to `install_sink_opt(default_channel(), Sink, Condition, Options)`.
install_sink_opt/4	Installs `Sink`
set_sink_condition/2	Equivalent to `set_sink_condition(default_channel(), SinkId, Condition)`.
set_sink_condition/3	Sets the applicable condition of the `SinkId`
uninstall_sink/1	Equivalent to `uninstall_sink(default_channel(), SinkId)`.
uninstall_sink/2	Uninstalls the sink which has the identifier `SinkId` from `Channel`
whereis_sink_proc/1	Equivalent to `whereis_sink_proc(default_channel(), Path)`.
whereis_sink_proc/2	Returns the pid associated with `Path`
which_channels/0	Returns a list of all existing channels.
which_sinks/0	Equivalent to `which_sinks(default_channel())`.
which_sinks/1	Returns a list of installed sinks.

Function Details

create/1

create(Channel::id()) -> ok

Creates a new channel

If the channel already exists, nothing happens.

If there exists a process or a ETS table with the same name as Channel, the function crashes.

default_channel/0

default_channel() -> id()

The default channel

This channel is created automatically when logi application was started.

NOTE: The default channel ID is the same as the default logger ID (logi:default_logger/0)

delete/1

delete(Channel::id()) -> ok

Deletes a channel

If the channel does not exists, it is silently ignored.

find_sink/1

find_sink(SinkId::logi_sink:id()) -> {ok, Sink::installed_sink()} | error

Equivalent to find_sink(default_channel(), SinkId).

find_sink/2

find_sink(Channel::id(), SinkId::logi_sink:id()) -> {ok, Sink::installed_sink()} | error

Searchs for SinkId in Channel

The function returns {ok, Sink}, or error if SinkId is not present

install_sink/2

install_sink(Sink::logi_sink:sink(), Condition::logi_condition:condition()) -> {ok, Old} | {error, Reason}

Old = undefined | installed_sink()
Reason = {cannot_start, term()}

Equivalent to install_sink(default_channel(), Sink, Condition).

install_sink/3

install_sink(Channel::id(), Sink::logi_sink:sink(), Condition::logi_condition:condition()) -> {ok, Old} | {error, Reason}

Old = undefined | installed_sink()
Reason = {cannot_start, term()}

Equivalent to install_sink_opt(Channel, Sink, Condition, []).

install_sink_opt/3

install_sink_opt(Sink::logi_sink:sink(), Condition::logi_condition:condition(), Options::install_sink_options()) -> {ok, Old} | {error, Reason}

Old = undefined | installed_sink()
Reason = {already_installed, installed_sink()} | {cannot_start, term()}

Equivalent to install_sink_opt(default_channel(), Sink, Condition, Options).

install_sink_opt/4

install_sink_opt(Channel::id(), Sink::logi_sink:sink(), Condition::logi_condition:condition(), Options::install_sink_options()) -> {ok, Old} | {error, Reason}

Old = undefined | installed_sink()
Reason = {already_installed, installed_sink()} | {cannot_start, term()}

Installs Sink

If failed to start a sink process specified by logi_sink:get_spec(Sink), the function returns {cannot_start, FailureReason}.

If there does not exist a sink which has the same identifier with a new one, the function returns {ok, undefined}.

Otherwise the result value depends on the value of the if_exists option (see the description of install_sink_option/0 for details).

set_sink_condition/2

set_sink_condition(SinkId::logi_sink:id(), Condition::logi_condition:condition()) -> {ok, Old::logi_condition:condition()} | error

Equivalent to set_sink_condition(default_channel(), SinkId, Condition).

set_sink_condition/3

set_sink_condition(Channel::id(), SinkId::logi_sink:id(), Condition::logi_condition:condition()) -> {ok, Old} | error

Old = logi_condition:condition()

Sets the applicable condition of the SinkId

The function returns {ok, Old} if the specified sink exists in the channel, error otherwise.

uninstall_sink/1

uninstall_sink(SinkId::logi_sink:id()) -> {ok, installed_sink()} | error

Equivalent to uninstall_sink(default_channel(), SinkId).

uninstall_sink/2

uninstall_sink(Channel::id(), SinkId::logi_sink:id()) -> {ok, Sink::installed_sink()} | error

Uninstalls the sink which has the identifier SinkId from Channel

The function returns {ok, Sink} if the specified sink exists in the channel, error otherwise.

Generated by EDoc