GELF Client

A typed GELF 1.1 client for Node.js with TCP and UDP transports.

Install

Choose your package manager:

# npm
npm install gelf-client

# Bun
bun add gelf-client

# Yarn
yarn add gelf-client

Quick start

This example sends one structured message over UDP:

import { randomUUID } from "node:crypto";
import GELFClient, { Level } from "gelf-client";

const client = GELFClient.factory("udp://localhost:12201/?compress");
client.transport.on("error", (error) => {
    console.error("GELF transport error", error);
});

try {
    await client.send({
        app: "checkout-api",
        level: Level.INFO,
        message: "Order accepted",
        request_id: randomUUID(),
        user_id: 42,
    });
} finally {
    client.close();
}

Graylog receives a GELF object with this shape:

{
    "version": "1.1",
    "host": "checkout-api",
    "short_message": "Order accepted",
    "timestamp": 1785196800,
    "level": 6,
    "_request_id": "a36f0d30-0b90-11ea-8d71-362b9e155667",
    "_user_id": 42
}

See the complete UDP example.

Transports

Use a connection string to select UDP or TCP:

import GELFClient from "gelf-client";

const udpClient = GELFClient.factory("udp://localhost:12201");
const tcpClient = GELFClient.factory("tcp://localhost:12201");

UDP supports GELF chunking and optional zlib compression. TCP writes each uncompressed, non-chunked JSON payload to a persistent socket and terminates it with a null byte. See the complete TCP example. Graylog documents the wire rules in its GELF format specification.

Defaults and request context

Pass stable application fields to factory(). Use clone() to add request-specific context without creating another socket:

import GELFClient from "gelf-client";

const client = GELFClient.factory("udp://localhost:12201", {
    app: "checkout",
    environment: "production",
});

const requestClient = client.clone({
    request_id: "req-123",
    user_id: 42,
});

await requestClient.info({
    message: "Payment captured",
    user_id: 43,
});

Fields passed to a log call override cloned and factory defaults. The message above uses user_id: 43. Clones share the original transport, so close the factory client when the application shuts down.

See the complete context example.

Message fields

The client maps standard fields to their GELF names:

Client field	GELF field	Required
message	short_message	yes
app	host	no
description	full_message	no
level	level	no
file	file	no
line	line	no

Any other property becomes a GELF custom field with an _ prefix. request_id becomes _request_id; you do not need to add the prefix yourself. When you omit app, the client uses the operating system hostname for the required GELF host field.

Client API

Member	Description
Client.factory(dsn, fields)	Create a client and optional default fields.
client.clone(fields)	Reuse the transport with merged defaults.
client.send(message)	Send a message with an optional explicit level.
client.emergency(message)	Send at Level.EMERGENCY.
client.alert(message)	Send at Level.ALERT.
client.critical(message)	Send at Level.CRITICAL.
client.error(message)	Send at Level.ERROR.
client.warning(message)	Send at Level.WARNING.
client.notice(message)	Send at Level.NOTICE.
client.info(message)	Send at Level.INFO.
client.debug(message)	Send at Level.DEBUG.
client.close()	Close the shared TCP or UDP transport.
client.transport	Access the transport and subscribe to its error event.
client.options	Read the parsed connection options.
client.defaults	Read the fields applied before message-specific fields.

send() and the level helpers return a promise. Await the promise before closing the client.

Levels

The values follow the syslog severity scale used by GELF:

Level	Value
Level.EMERGENCY	0
Level.ALERT	1
Level.CRITICAL	2
Level.ERROR	3
Level.WARNING	4
Level.NOTICE	5
Level.INFO	6
Level.DEBUG	7

send() uses Level.INFO when you omit level.

Connection string

Use this DSN form:

protocol://host[:port]/?flag&option=value

For example:

udp://graylog.internal:12201/?compress&strict&maxChunkSize=1400

Item	Default	Description
protocol	-	udp or tcp.
port	12201	Graylog GELF input port in the range 1..65535.
compress	off	Compress chunked UDP payloads with zlib.
maxChunkSize	1400	Maximum UDP chunk size in bytes.
minCompressSize	1400	Compression threshold used by the serializer.
strict	env	Reject custom field names outside letters, digits, _.

Strict custom-field validation runs when the DSN contains strict or NODE_ENV !== "production".

Errors and shutdown

TCP connection errors, UDP socket errors, and serialization errors use the transport's error event. Register a listener before sending:

import GELFClient from "gelf-client";

const client = GELFClient.factory("udp://localhost:12201");
client.transport.on("error", (error) => {
    console.error("GELF transport error", error);
});

Call client.close() during application shutdown. A cloned client shares its factory client's transport, so close that transport once.

Development

Install the locked dependencies:

bun ci

Run individual checks:

bun test
bun run test:watch
bun run lint
bun run fmt
bun run build

Run the same gate as CI:

bun run check

The full check covers formatting, linting, source and example type-checking, Bun tests, package build, and a packed-package consumer test.

License

MIT