:plugin: gelf
:type: output
:default_codec: plain

///////////////////////////////////////////
START - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////
:version: %VERSION%
:release_date: %RELEASE_DATE%
:changelog_url: %CHANGELOG_URL%
:include_path: ../../../../logstash/docs/include
///////////////////////////////////////////
END - GENERATED VARIABLES, DO NOT EDIT!
///////////////////////////////////////////

[id="plugins-{type}s-{plugin}"]

=== Gelf output plugin

include::{include_path}/plugin_header.asciidoc[]

==== Description

This output generates messages in GELF format. This is most useful if you
want to use Logstash to output events to Graylog2.

More information at http://docs.graylog.org/en/2.3/pages/gelf.html#gelf-payload-specification[The Graylog2 GELF specs page]

[id="plugins-{type}s-{plugin}-options"]
==== Gelf Output Configuration Options

This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.

[cols="<,<,<",options="header",]
|=======================================================================
|Setting |Input type|Required
| <<plugins-{type}s-{plugin}-chunksize>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-custom_fields>> |<<hash,hash>>|No
| <<plugins-{type}s-{plugin}-full_message>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-host>> |<<string,string>>|Yes
| <<plugins-{type}s-{plugin}-ignore_metadata>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-level>> |<<array,array>>|No
| <<plugins-{type}s-{plugin}-port>> |<<number,number>>|No
| <<plugins-{type}s-{plugin}-protocol>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-sender>> |<<string,string>>|No
| <<plugins-{type}s-{plugin}-ship_metadata>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-ship_tags>> |<<boolean,boolean>>|No
| <<plugins-{type}s-{plugin}-short_message>> |<<string,string>>|No
|=======================================================================

Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
output plugins.

&nbsp;

[id="plugins-{type}s-{plugin}-chunksize"]
===== `chunksize` 

  * Value type is <<number,number>>
  * Default value is `1420`

The chunksize. You usually don't need to change this.

[id="plugins-{type}s-{plugin}-custom_fields"]
===== `custom_fields` 

  * Value type is <<hash,hash>>
  * Default value is `{}`

The GELF custom field mappings. GELF supports arbitrary attributes as custom
fields. This exposes that. Exclude the `_` portion of the field name
e.g. `custom_fields => ['foo_field', 'some_value']`
sets `_foo_field` = `some_value`.

[id="plugins-{type}s-{plugin}-full_message"]
===== `full_message` 

  * Value type is <<string,string>>
  * Default value is `"%{message}"`

The GELF full message. Dynamic values like `%{foo}` are permitted here.

[id="plugins-{type}s-{plugin}-host"]
===== `host` 

  * This is a required setting.
  * Value type is <<string,string>>
  * There is no default value for this setting.

Graylog2 server IP address or hostname.

[id="plugins-{type}s-{plugin}-ignore_metadata"]
===== `ignore_metadata` 

  * Value type is <<array,array>>
  * Default value is `["@timestamp", "@version", "severity", "host", "source_host", "source_path", "short_message"]`

Ignore these fields when `ship_metadata` is set. Typically this lists the
fields used in dynamic values for GELF fields.

[id="plugins-{type}s-{plugin}-level"]
===== `level` 

  * Value type is <<array,array>>
  * Default value is `["%{severity}", "INFO"]`

The GELF message level. Dynamic values like `%{level}` are permitted here;
useful if you want to parse the 'log level' from an event and use that
as the GELF level/severity.

Values here can be integers [0..7] inclusive or any of
"debug", "info", "warn", "error", "fatal" (case insensitive).
Single-character versions of these are also valid, "d", "i", "w", "e", "f",
"u"
The following additional severity\_labels from Logstash's  syslog\_pri filter
are accepted: "emergency", "alert", "critical",  "warning", "notice", and
"informational".

[id="plugins-{type}s-{plugin}-port"]
===== `port` 

  * Value type is <<number,number>>
  * Default value is `12201`

Graylog2 server port number.

[id="plugins-{type}s-{plugin}-protocol"]
===== `protocol`

By default, this plugin outputs via the UDP transfer protocol, but can be
configured to use TCP instead.

  * Value type is <<string,string>>
  * Default value is `"UDP"`

Values here can be either "TCP" or "UDP".

[id="plugins-{type}s-{plugin}-sender"]
===== `sender` 

  * Value type is <<string,string>>
  * Default value is `"%{host}"`

Allow overriding of the GELF `sender` field. This is useful if you
want to use something other than the event's source host as the
"sender" of an event. A common case for this is using the application name
instead of the hostname.

[id="plugins-{type}s-{plugin}-ship_metadata"]
===== `ship_metadata` 

  * Value type is <<boolean,boolean>>
  * Default value is `true`

Should Logstash ship metadata within event object? This will cause Logstash
to ship any fields in the event (such as those created by grok) in the GELF
messages. These will be sent as underscored "additional fields".

[id="plugins-{type}s-{plugin}-ship_tags"]
===== `ship_tags` 

  * Value type is <<boolean,boolean>>
  * Default value is `true`

Ship tags within events. This will cause Logstash to ship the tags of an
event as the field `\_tags`.

[id="plugins-{type}s-{plugin}-short_message"]
===== `short_message` 

  * Value type is <<string,string>>
  * Default value is `"short_message"`

The GELF short message field name. If the field does not exist or is empty,
the event message is taken instead.



[id="plugins-{type}s-{plugin}-common-options"]
include::{include_path}/{type}.asciidoc[]

:default_codec!: