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, "~> 2.0.0"} to your list of dependencies in mix.exs:

def deps do
  [
    # ...
    {:gelfx, "~> 2.0.0"}
  ]
end

And adding it to your :logger configuration in config.exs:

config :logger,
  backends: [
    :console,
    Gelfx
  ]

Since Elixir 1.15 Logger backends live in the :logger_backends package, which Gelfx depends on. Backends can also be added at runtime using LoggerBackends.add/1:

LoggerBackends.add(Gelfx)

Since GELF relies on json to encode the payload Gelfx uses the JSON module included in Elixir (requires Elixir 1.18 or later).

Options

Besides :level, :format and :metadata, which are advised by Logger Gelfx supports:

• :host - hostname of the server running the GELF endpoint, defaults to localhost
• :port - port on which the graylog server runs the respective GELF input, defaults to 12201
• :protocol - either :tcp, :udp, or :http. 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 or HTTP (only gzip) 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()
• :utc_log - this option should not be configured directly. But rather by setting the :utc_log option in the Logger config. Should the Logger config change after the Gelfx backend is initialized the option has to be reconfigured.

HTTP

When using the HTTP protocol the url is build using the scheme defined in the graylog documentation.

Setting the host to localhost and port to 12201 sends log entries to http://localhost:12201/gelf.

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.

Custom formatting

You can use your own log formatter in the same way you would define one for the Elixir default Logger. More information can be found here in the Logger documentation.

  config :logger, Gelfx,
    format: {MyCustomFormatter, :format}

Levels

Graylog relies on the syslog definitions for logging levels. Gelfx maps the Elixir levels as follows: