Skip to content

Latest commit

 

History

History
72 lines (48 loc) · 4.15 KB

README.md

File metadata and controls

72 lines (48 loc) · 4.15 KB
Raw

journald2graylog

Build Status

Command line tool to help forward systemd's journald's logs to a Graylog server taking advantage of the descriptive GELF format.

The journald2graylog command expects it's paramters to be provided as the environment variables, making it well suited for Docker or systemd driven environments, and PaaS platforms like Heroku and the Twelve-Factor App approach.

Usage

To use journald2graylog, you simply pipe the output of journalctl, while enabling it's JSON output format, into the jourald2graylog command. It can be as simple this: journalctl -o json | journald2graylog, but usually you will require and want to provide more parameters.

Note that journald2graylog only supports UDP for now, having TCP might be cool, but it's not in our short term plans.

There are four configuration parameters:

  • The J2G_HOSTNAME is the hostname or IP of your Graylog server, it has no default and MUST be specified.
  • The J2G_PORT is the port of the UDP GELF input of the Graylog server, it will default to 12201, but this value will almost always differ depending on your Graylog configuration, so you will most likely have to look it up in your own Graylog server.
  • The J2G_PACKET_SIZE is the maximum size of the TCP/IP packets you can use between the source (journald2graylg) and the destination (your Graylog server). This will vary depending on your network capabilities, but the default value of 1420 will be appropriate in the vast majority of situations.
  • The J2G_BLACKLIST is a list containing regex identifying logs that must not be sent to Graylog, separated by a semicolon (;).

You can add debugging by specifying the --verbose (also -v) flag, it will display the configuration parameters sent to journald2graylog in stdout

Note that from version 0.2.0 onward, journald2graylog will now exit if there is a network error, instead of looping forever. This makes a network problem more visible, and also gives Kubernetes (or a bash script, or systemd, etc) a chance to restart the application, which might end up resolving this kind of network problem.

Example usage

This example uses all available configuration parameters, provided as environment variables:

export J2G_HOSTNAME=graylog.example.com
export J2G_PORT=12201
export J2G_PACKET_SIZE=1420
export J2G_BLACKLIST="foo.*;bar.*"
sudo journalctl -o json -f | journald2graylog --verbose

Or you can simply do:

journalctl -o json -f | J2G_HOSTNAME=graylog.example.com journald2graylog

And depending on your context, you might actually need to use something more among the line of:

sudo journalctl -o json -f | J2G_HOSTNAME=graylog.example.com ./journald2graylog

Note that if a parameter specified via an environment variable will override the same parameter specified via command line. For example, in the following command, the blacklist parameter will be set to localhost and not remotehost :

J2G_BLACKLIST=localhost journald2graylog --blacklist remotehost

Install

From source, you will have to already have a working go development environment setup, with a proper GOPATH.

go get github.com/cdemers/journald2graylog

The resulting binary should be compiled and placed in your GOPATH tree as $GOPATH/bin/journald2graylog.

From binary, you can download the latest precompiled binary (Linux AMD64) from the release section.

Using make, running make or make all will build a single binary for your current platform.

Building for Docker

Using make, you can build a docker image by running make docker, it will build the Linux binary and a docker image from Dockerfile, and attempt to push image to a docker registry. You must use your own registry by specifying DOCKER_REGISTRY, for example:

make docker -e DOCKER_REGISTRY=private.registry.org