gelfx v0.2.1 Gelfx View Source
A logger backend for Elixir applications using Logger
and Graylog based on GELF (Graylog extended logging format).
Usage
Add Gelfx to your application by adding {:gelfx, "~> 0.2.1"}
to your list of dependencies in mix.exs
:
def deps do
[
# ...
{:gelfx, "~> 0.2.1"}
]
end
And adding it to your :logger
configuration in config.exs
:
config :logger,
backends: [
:console,
Gelfx
]
Since GELF relies on json to encode the payload Gelfx will need a JSON library. By default Gelfx will use Jason which needs to be added to your deps in mix.exs:
{:jason, "~> 1.0"}
Options
Besides :level
, :format
and :metadata
, which are advised by Logger Gelfx supports:
:host
- hostname of the server running the GELF endpoint, defaults tolocalhost
:port
- port on which the graylog server runs the respective GELF input, defaults to12201
:protocol
- either:tcp
or:udp
,:http
is not jet supported, defaults to:udp
:connection_timeout
- sets the timeout in ms after which the:tcp
connect timeouts, defaults to 5s.:compression
- either:gzip
or:zlib
can be set and will be used for package compression when UDP is used as protocol:format
- defaults to"$message"
:hostname
- used as source field in the GELF message, defaults to the hostname returned by:inet.gethostname()
:json_library
- json library to use, has to implement aencode/1
which returns a{:ok, json}
tuple in case of success:utc_log
- this option should not be configured directly. But rather by setting the:utc_log
option in theLogger
config. Should the Logger config change after the Gelfx backend is initialized the option has to be reconfigured.
Message Format
The GELF message format version implemented by this library is 1.1, the docs can be found here.
Messages can include a short_message
and a full_message
, Gelfx will use the first line of each log message for the short_message
and will place the whole message in the full_message
field.
Metadata will be included in the message using the additional field syntax.
The Keys of the metadata entries have to match ^\_?[\w\.\-]*$
, keys missing an leading underscore are automatically prepended with one.
Key collisions are NOT prevented by Gelfx, additionally the keys id
and _id
are automatically omitted due to the GELF specification.
Levels
Graylog relies on the syslog definitions for logging levels. Gelfx maps the Elixir levels as follows:
Elixir | Sysylog | GELF - Selector |
---|---|---|
Emergency | 0 | |
Alert | 1 | |
Critical | 2 | |
:error | Error | 3 |
:warn | Warning | 4 |
Notice | 5 | |
:info | Informational | 6 |
:debug | Debug | 7 |
Link to this section Summary
Functions
Encodes the given LogEntry
using the configured json library
Spawns a :gen_udp
/ :gen_tcp
connection based on the configuration
Sends the given payload over the connection.
Link to this section Functions
encode(log_entry, state) View Source
Encodes the given LogEntry
using the configured json library
init(config, state) View Source
spawn_conn(state) View Source
Spawns a :gen_udp
/ :gen_tcp
connection based on the configuration
spawn_conn(protocol, host, port, timeout) View Source
submit(payload, gelfx) View Source
Sends the given payload over the connection.
In case an TCP connection is used the 0x00
delimiter required by gelf is added.
Should the used connection use UDP the payload is compressed using the configured compression, in case the given payload exceeds the chunk threshold it is chunked.