Skip to content

GELF messages and transports

Most applications send logs through a log client, which batches records, redacts secrets and turns them into GELF messages. The GELF layer underneath is public too, for tools that want full control over the wire format.

GelfMessage

A GELF 1.1 message: version "1.1", host (stored as source), short_message (stored as message), optional full_message, timestamp (Unix seconds with millisecond precision) and level (syslog 0–7), plus additional fields _<name>. Explicit field keys are validated: only [A-Za-z0-9_.-], never empty and never the reserved id (VALIDATION otherwise).

Records from the logging API map to GELF the same way in every language:

Record GELF
severity TRACE, DEBUG / INFO / WARN / ERROR / FATAL level 7 / 6 / 4 / 3 / 2 (reverse: 0–2 → FATAL, 3 → ERROR, 4 → WARN, 5–6 → INFO, 7 → DEBUG)
body short_message; a blank body is sent as "-" (Graylog drops messages without one)
attribute key _ + key with every character outside [A-Za-z0-9_.-] replaced by _ (ASCII only); id → _attr_id
string / number value unchanged
boolean "true" / "false" (Graylog drops JSON booleans)
null omitted
array / object compact JSON string
resource attributes flattened with their dotted keys (_service.name, _deployment.environment)
trace id / span id / trace flags _trace_id, _span_id (lower-case hex), _trace_flags (number)

Transports

Transport Wire Notes
GelfUdpTransport one datagram per message; gzip (default), zlib or none; messages larger than the chunk size (default 1420 bytes) are split into GELF chunks (0x1e 0x0f + 8-byte id + sequence + count), at most 128 chunks (VALIDATION above that) fire-and-forget: delivery is best-effort
GelfTcpTransport one persistent connection, each message JSON + one NUL byte; optional TLS (CA, client certificate) reconnects with backoff after a broken connection (at-least-once: a batch may be delivered twice)
GelfHttpTransport POST <url> (default http://<gelfHost>:12202/gelf), newline-delimited bulk body, gzip by default every message ends with \n, also single-message bodies (Graylog 7.0 otherwise drops the first message of later requests on a reused connection). Graylog answers 202 even for invalid messages, so messages are validated client-side.
gelfTransport(protocol) — builds the transport for udp, tcp or http from the client configuration (gelfHost, gelfPort, gelfHttpUrl, gelfTls, timeouts, retries)
GelfLogExporter — a LogExporter over any GELF transport, for BatchingLogClient

Each transport's send(messages) returns {sent, rejected}; close() releases the socket.

import { GelfLevel, GelfMessage, GelfUdpTransport, GraylogClient } from "@grow-codes/graylog";

const client = GraylogClient.fromEnv();
const tcp = client.gelfTransport("tcp"); // host/port/TLS from the config
const message = new GelfMessage({
  host: "checkout-1",
  shortMessage: "payment failed",
  fullMessage: "stack trace…",
  level: GelfLevel.Error,
  fields: { order_id: "o-1", amount: 12.5, retried: true }, // retried → "true"
});
console.log(await tcp.send([message])); // { sent: 1, rejected: 0 }
await tcp.close();

const udp = new GelfUdpTransport({ host: "graylog", port: 12201, compression: "zlib" });
await udp.send([message]);
await udp.close();
use std::sync::Arc;
use grow_graylog::{
    GelfLevel, GelfMessage, GelfMessageOptions, GelfProtocol, GelfSendOptions,
    GelfTransportOptions,
};
use grow_graylog::logging::attrs;

let tcp = client.gelf_transport(Some(GelfProtocol::Tcp), GelfTransportOptions::default())?;
let message = GelfMessage::new(GelfMessageOptions {
    host: "checkout-1".into(),
    short_message: "payment failed".into(),
    level: Some(GelfLevel::Error),
    fields: attrs! { "order_id" => "o-1", "amount" => 12.5 },
    ..Default::default()
})?;
let result = tcp.send(&[message], GelfSendOptions::default()).await?;
println!("sent {}", result.sent);
tcp.close().await?;
tcp, err := client.GelfTransport(graylog.GelfTCP, graylog.GelfTransportOptions{})
if err != nil {
    return err
}
defer tcp.Close()
level := graylog.GelfLevelError
msg, err := graylog.NewGelfMessage(graylog.GelfMessageOptions{
    Host: "checkout-1", ShortMessage: "payment failed", Level: &level,
    Fields: map[string]any{"order_id": "o-1", "amount": 12.5},
})
res, err := tcp.Send(ctx, []*graylog.GelfMessage{msg}, graylog.GelfSendOptions{})
fmt.Println(res.Sent, res.Rejected)

udp, err := graylog.NewGelfUDPTransport(graylog.GelfUDPOptions{Host: "graylog", Port: 12201, Compression: graylog.GelfCompressionZlib})
import grow_graylog as sdk

with sdk.GraylogClient.from_env() as client:
    tcp = client.gelf_transport("tcp")
    message = sdk.GelfMessage(
        "checkout-1",
        "payment failed",
        level=sdk.GelfLevel.ERROR,
        fields={"order_id": "o-1", "amount": 12.5, "retried": True},
    )
    print(tcp.send([message]))  # GelfSendResult(sent=1, rejected=0)
    tcp.close()

    udp = sdk.GelfUdpTransport("graylog", 12201, compression="zlib")
    udp.send([message])
    udp.close()
import codes.grow.packages.graylog.*;
import java.util.List;

GelfTransport tcp = client.gelfTransport(GelfProtocol.TCP);
GelfMessage message =
    GelfMessage.builder("checkout-1", "payment failed")
        .level(3)
        .field("order_id", "o-1")
        .field("amount", 12.5)
        .build();
System.out.println(tcp.send(List.of(message)).sent());
tcp.close();

GelfTransport udp = GelfUdpTransport.builder("graylog").port(12201).build();
udp.send(List.of(message));
udp.close();