Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

GELF

The Graylog Extended Log Format (GELF) avoids the shortcomings of classic plain syslog:

  • Limited to length of 1024 byte – not much space for payloads like backtraces.
  • Unstructured. You can only build a long message string and define priority, severity etc.

Syslog is okay for logging system messages of you servers. Use it for that. GELF instead is great for logging from within applications. It is a good practice to send GELF messages directly from your existing logging classes so it is very easy to integrate into existing applications. You could use GELF to send every exception as a log message to your Graylog2 server. You don't have to care about timeouts, connection problems or anything that might break your application from within your logging class because GELF is sent via UDP. The disadvantage of this fire and forget principle is of course that no one guarantees that your GELF message will ever arrive. I'd say that important messages will just occur again. TCP support for those who like it is coming though.

Chunked GELF

UDP datagrams are limited in size. A lot of compressed information is fitting in there but you sometimes might just have more information to send. This is why Graylog2 supports chunked GELF. You can define chunks of messages by prepending a byte header to a GELF message including a GELF ID, a message ID and sequence count/number to reassemble the message later. The client library will detect if the message is too long and will perform the chunking itself.

Structure of Chunked GELF header

Prepend the following structure before your GELF message to make it chunked:

  • Chunked GELF ID: 0x1e 0x0f (identifying this message as a chunked GELF message)
  • Message ID: 8 bytes (Must be the same for every chunk of this message. Identifying the whole message itself and is used to reassemble the chunks later. Generate from microsecond timestamp + hostname for example)
  • Sequence Number: 1 byte (The sequence number of this chunk)
  • Total Number: 1 byte (How many chunks does this message consist of in total)

Specification (version 1.0)

A GELF message is a GZIP'd or ZLIB'd JSON string with the following fields:

  • _version: GELF spec version – "1.0" (string); MUST be set by client library.
  • _host: the name of the host or application that sent this message (string); MUST be set by client library.
  • _short_message: a short descriptive message (string); MUST be set by client library.
  • _full_message: a long message that can i.e. contain a backtrace and environment variables (string); optional.
  • _timestamp: UNIX UTC timestamp (float); SHOULD be set by client library; MUST be set by server if empty.
  • _level: the level equal to the standard syslog levels (decimal); optional, default is FIXME.
  • _facility: (String) optional, MUST be set by server to GELF if empty.
  • _line: the line in a file that caused the error (decimal); optional.
  • _file: the file (with path if you want) that caused the error (string); optional.
  • [additional fields]: every other field you send will be treated as an additional field. MUST NOT start with _.

Predefined GELF fields are prepended with _ to avoid collision with user-defined fields. Client libraries are expected to automatically fill some of those fields.

Example GELF message:

{
  "_version": "1.0",
  "_host": "www1",
  "_short_message": "Short message",
  "_full_message": "Backtrace here\n\nmore stuff",
  "_timestamp": 1291899928.53958,
  "_level": 1,
  "_facility": "webapp",
  "_file": "/var/www/somefile.rb",
  "_line": 356,
  "user_id": 42,
  "something_else": "foo"
}

Magic values

Compressed message starts from 0x78 0x9c (ZLIB'd) or 0x1f 0x8b (GZIP'd) bytes. Chunked message starts from 0x1e 0x0f.

Something went wrong with that request. Please try again.