README

graylog-client

This library was created in order to easily integrate Graylog into a JS client by handling the requests in GELF format for you.

Requirements

In order to make use of the library, your Graylog instance needs to be configured to handle the GELF HTTP input.

Installation

Yarn

yarn add @navigraph/graylog-client

NPM

npm install @navigraph/graylog-client

Usage

Simple

import GraylogClient from 'graylog-client';

const glc = new GraylogClient({
  server: 'https://log.example.org',
  source: 'sample-app',
});

glc.info('An informative message.');
glc.warning('Something is about to happen!');

Advanced

import GraylogClient from 'graylog-client';
import { v4 as uuid } from 'uuid';

interface GraylogExtras {
  facility: string;
  stack: string;
}

const glc = new GraylogClient<GraylogExtras>({
  server: 'https://log.example.org',
  source: 'sample-app',
  idGenerator: uuid,
});

glc.error('An error ocurred in the pizza component!', {
  facility: 'Pizza',
  stack: '* stack trace *',
});

Constructor

Property	Type	Description	Required
server	string	The endpoint to which the requests should be sent, including protocol.	yes
source	string	The client from which the logs are sent.	yes
idGenerator	function	A generator function that returns a string to use as ID for each log request.	no

Typescript

If typescript is used, an optional type generic may be passed to the constructor. This can be used to type the extra information sent with each request (see the Advanced Example for an example implementation), but is not required.

Available methods

The GraylogClient contains multiple convenience methods mapping directly towards syslog's severity levels.

Method	Severity	Description	Condition
emergency	Emergency	System is unusable	A panic condition. [1]
alert	Alert	Action must be taken immediately	A condition that should be corrected immediately, such as a corrupted system database. [1]
critical	Critical	Critical conditions	Hard device errors. [1]
error	Error	Error conditions
warning	Warning	Warning conditions
notice	Notice	Normal but significant conditions	Conditions that are not error conditions, but that may require special handling. [1]
info	Informational	Informational messages
debug	Debug	Debug-level messages	Messages that contain information normally of use only when debugging a program. [1]

Each method may be called with two parameters in accordance with the specification below.

Parameter	Type	Description	Required
message	string	The short (summary) message to display in Graylog.	yes
extras	object	Any extra information, not including the source client. This object may be typed using a generic in the constructor, see Constructor.	no

Contributing

For guidelines and useful information, please see CONTRIBUTING.md

License

MIT

Usage no npm install needed!