logi_ex v0.1.1 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
Options for install_sink_opt/3
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
Installs sink
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
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() :: %{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
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.
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
).
Deletes a channel.
If the channel does not exists, it is silently ignored.
Equivalent to Logi.Channel.find_sink Logi.Channel.id, sink_id
.
Searches for sink_id
in channel
.
The function returns {:ok, sink}
, or :error
if sink_id
is not present.
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(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(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(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(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(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.
Equivalent to Logi.Channel.uninstall_sink Logi.Channel.default_channel, sink_id
.
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.
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.