Skip to main content
Version: Next

gelf

Reads Graylog Extended Log Format (GELF) events.

Synopsis

Parser:

gelf [--merge] [--schema <schema>] [--selector <fieldname[:prefix]>]
[--schema-only] [--raw] [--unnest-separator <separator>]

Description

The gelf parser reads events formatted in Graylog Extended Log Format (GELF), a format that predominantly Graylog uses for importing and exporting of structured data.

Tenzir parses GELF as a stream of JSON records separated by a \0 byte. GELF messages can also occur one at a time (e.g., framed in a HTTP body, UDP packet, or Kafka message) in which case there is no separator.

GELF also supports a chunked mode where a single message can be split into at most 128 chunks. Tenzir currently does not support this mode. Please reach out if you would like to see support in future versions.

According to version 1.1 of the specification, a GELF message has the following structure:

FieldTypeDescriptionRequirement
versionstringGELF spec version: "1.1"
hoststringHost, source, or application name
short_messagestringA short descriptive message
full_messagestringLong message, possibly with a backtrace
timestampnumberUNIX epoch seconds; optional milliseconds
levelnumberStandard syslog level, defaults to 1
facilitystringMessage tag
linenumbernumberLine causing the error
filestringFile causing the error
_[additional field]string / numberUser-defined data

The requirement column defines whether a field is mandatory (✅), optional (➖), or deprecated (❌).

Here is an example GELF message:

{
  "version": "1.1",
  "host": "example",
  "short_message": "TL;DR",
  "full_message": "The whole enchilada",
  "timestamp": 1385053862.3072,
  "level": 1,
  "_user_id": 1337,
  "_gl2_remote_ip": "6.6.6.6",
}

By convention, Graylog uses the _gl2_ prefix for its own fields. There is no formalized convention for naming, and exact field names may depend on your configuration.

Boolean values

Graylog's implementation of GELF does not support boolean values and drops them on ingest.

Common Options (Parser)

The GELF parser supports the common schema inference options.

Examples

Accept GELF from a TCP socket:

from tcp://1.2.3.4 read gelf

Read GELF messages from Kafka from the graylog topic:

from kafka --topic graylog read gelf