logi_ex v0.1.0 Logi.Channel

Log Message Channels.

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

Examples

# CREATE CHANNEL
iex> :ok = Logi.Channel.create :sample_log
iex> Logi.Channel.which_channels
[:sample_log, :logi_default_log] # 'logi_default_log' is created automatically when 'logi' application was started

# INSTALL SINK
iex> write_fun = fn (_, format, data) -> :io.format("[my_sink] " <> format <> "\n", data) end
iex> sink = Logi.BuiltIn.Sink.Fun.new :sample_sink, write_fun
iex> {:ok, _} = Logi.Channel.install_sink :sample_log, sink, :info  # Installs `sink` with `:info` level
iex> Logi.Channel.which_sinks :sample_log
[:sample_sink]

# OUTPUT LOG MESSAGE
iex> require Logi
iex> Logi.debug "hello world", [], [logger: :sample_log]
# The message is not emitted (the severity is too low).

iex> Logi.info "hello world", [], [logger: :sample_log]
#OUTPUT# [my_sink] hello world

iex> Logi.alert "hello world", [], [logger: :sample_log]
#OUTPUT# [my_sink] hello world

iex> 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).

Summary

Types

The identifier of a channel

The information of an installed sink

Functions

Creates a new channel

The default channel

Deletes a channel

Equivalent to Logi.Channel.find_sink Logi.Channel.id, sink_id

Searches for sink_id in channel

Equivalent to Logi.Channel.install_sink Logi.Channel.default_channel, sink, condition

Equivalent to Logi.Channel.install_sink_opt channel, sink, condition, []

Equivalent to Logi.Channel.install_sink_opt Logi.Channel.default_channel, sink, condition, options

Equivalent to Logi.Channel.set_sink_condition Logi.Channel.default_channel, sink_id, condition

Sets the applicable condition of the sink_id

Equivalent to Logi.Channel.uninstall_sink Logi.Channel.default_channel, sink_id

Uninstalls the sink which has the identifier sink_id from channel

Equivalent to Logi.Channel.whereis_sink_proc Logi.Channel.default_channel, path

Returns the pid associated with path

Returns a list of all existing channels

Returns a list of installed sinks

Types

id()
id() :: atom

The identifier of a channel

install_sink_options()
install_sink_options() :: [{:if_exists, :error | :ignore | :supersede}]

Options for install_sink_opt/3.

if_exists

  • The confliction handling policy.
  • If a sink with the same identifier already exists,

    • :error: the function returns an error {:error, {:already_installed, existing_sink}}.
    • :ignore: the new sink is ignored. Then the function returns {:ok, existing_sink}.
    • :supersede: the new sink supersedes it. Then the function returns {:ok, old_sink}.
  • Default: :supersede
installed_sink()
installed_sink() :: %{sink: Logi.Sink.sink, condition: Logi.Confliction.condition, sink_sup: Logi.SinkProc.sink_sup, writer: Logi.SinkWriter.writer | :undefined}

The information of an installed sink.

Functions

create(channel)
create(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()
default_channel() :: id

The default channel.

This channel is created automatically when logi_ex application was started.

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

delete(channel)
delete(id) :: :ok

Deletes a channel.

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

find_sink(sink_id)
find_sink(Logi.Sink.id) :: {:ok, installed_sink} | :error

Equivalent to Logi.Channel.find_sink Logi.Channel.id, sink_id.

find_sink(channel_id, sink_id)
find_sink(id, Logi.Sink.id) :: {:ok, installed_sink} | :error

Searches for sink_id in channel.

The function returns {:ok, sink}, or :error if sink_id is not present.

install_sink(sink, condition)
install_sink(Logi.Sink.sink, Logi.Condition.condition) ::
  {:ok, old} |
  {:error, reason} when old: :undefined | installed_sink, reason: {:cannot_start, any}

Equivalent to Logi.Channel.install_sink Logi.Channel.default_channel, sink, condition.

install_sink(channel, sink, condition)
install_sink(id, Logi.Sink.sink, Logi.Condition.condition) ::
  {:ok, old} |
  {:error, reason} when old: :undefined | installed_sink, reason: {:cannot_start, any}

Equivalent to Logi.Channel.install_sink_opt channel, sink, condition, [].

install_sink_opt(sink, condition, options)
install_sink_opt(Logi.Sink.sink, Logi.Condition.condition, install_sink_options) ::
  {:ok, old} |
  {:error, reason} when old: :undefined | installed_sink, reason: {:cannot_start, any} | {:already_installed, installed_sink}

Equivalent to Logi.Channel.install_sink_opt Logi.Channel.default_channel, sink, condition, options.

install_sink_opt(channel, sink, condition, options)
install_sink_opt(id, Logi.Sink.sink, Logi.Condition.condition, install_sink_options) ::
  {:ok, old} |
  {:error, reason} when old: :undefined | installed_sink, reason: {:cannot_start, any} | {:already_installed, installed_sink}

Installs sink.

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

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_options/0 for details).

set_sink_condition(sink_id, condition)
set_sink_condition(Logi.Sink.id, Logi.Condition.condition) ::
  {:ok, old} |
  :error when old: Logi.Condition.condition

Equivalent to Logi.Channel.set_sink_condition Logi.Channel.default_channel, sink_id, condition.

set_sink_condition(channel, sink_id, condition)
set_sink_condition(id, Logi.Sink.id, Logi.Condition.condition) ::
  {:ok, old} |
  :error when old: Logi.Condition.condition

Sets the applicable condition of the sink_id.

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

uninstall_sink(sink_id)
uninstall_sink(Logi.Sink.id) :: {:ok, installed_sink} | :error

Equivalent to Logi.Channel.uninstall_sink Logi.Channel.default_channel, sink_id.

uninstall_sink(channel, sink_id)
uninstall_sink(id, Logi.Sink.id) ::
  {:ok, installed_sink} |
  :error

Uninstalls the sink which has the identifier sink_id from channel.

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

whereis_sink_proc(path)
whereis_sink_proc([Logi.Sink.id]) :: pid | :undefined

Equivalent to Logi.Channel.whereis_sink_proc Logi.Channel.default_channel, path.

whereis_sink_proc(channel, path)
whereis_sink_proc(id, [Logi.Sink.id]) :: pid | :undefined

Returns the pid associated with path.

which_channels()
which_channels() :: [id]

Returns a list of all existing channels.

which_sinks(channel \\ Logi.Channel.default_channel())
which_sinks(id) :: [Logi.Sink.id]

Returns a list of installed sinks.