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 https://github.com/Navigraph/graylog-client.git

NPM

npm install https://github.com/Navigraph/graylog-client.git

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