@trackcode/gelf

@trackcode/gelf

GELF HTTP Client, includes typed events, express middleware and the possibility to use Basic Auth.

Usage

Install the package:

npm i @trackcode/gelf

Now you have to create an instance of the GELF class.

// src/utils/gelf.js
const GELF = require("@trackcode/gelf");

export default const gelf = new GELF({
  application: "name-of-your-service",
  environment: process.env.NODE_ENV,
  gelfEndpoint: process.env.GELF_ENDPOINT
})

Endpoint

The endpoint can be any valid URI. In the simplest example this would directly be the GELF HTTP endpoint from Graylog:

gelfEndpoint: "http://graylog.example.com:12201/gelf";

But maybe you want your ingress secured with HTTPS, so you deploy nginx infront of graylog:

gelfEndpoint: "https://graylog.example.com/gelf";

And then, you want to be sure that only you can push events to Graylog, so you add Basic Auth in the nginx config:

gelfEndpoint: "https://username:[e-mail]/gelf";

Emitting Events

You can send events to graylog through the GELF.emit method:

// src/server.js
const gelf = require("./utils/gelf");

gelf.emit({
  /* Your event */
});

The content of the emitted event can be whatever you want. Keep in mind the constraints of Graylog and Elasticsearch (> 32kb cant be indexed, field can only ever have one type).

Few fields are constant, or predefined by the specification. They are defined in src/gelf/event.ts.

Using typed events

If you want to use typed events with a known structure, because they are easier to handle in Graylog and built Elasticsearch Indices around, then today is your lucky day.

This package comes with a set of predefined Events. You can find them in the src/events folder. They expose a fluent interface to set the values.

// src/server.js
const { Events } = require("@trackcode/gelf");
const gelf = require("./utils/gelf");

function logMiddleware(req, res, next) {
  gelf.emit(
    new Events.HTTPRequestEvent()
      .method(req.method)
      .headers(req.headers)
      .originalURL(req.originalUrl)
      .route(req.path)
      .body(req.body)
  );

  next();
}

All events have a special property _kind which is unique for the Event. You should use this property to differentiate events in Graylog Pipelines and other consumers.

Logging HTTP Requests

There is a bundled middleware logRequest for express. It waits until the request is finished and emits details about request and response as a HTTPRequestEvent (check out the documentation about Typed Events to learn more).

// src/server.js
const { logRequest } = require("@trackcode/gelf");
const express = require("express");
const gelf = require("./utils/gelf");

const app = express();

app.use(logRequest({ gelf: gelf }));

// Route handlers that will be logged
app.get("/", (req, res) => {});

app.listen(8080, console.log);
}

Transformers

Transformers can be compared to an express middleware. They receive req, res and the httpEvent and can modify the event based on this information.

They should be used when you want to add application specific information to your events. For example if your req object contains session information, then you could use following transformer to add that information to the event:

// src/server.js

const middleware = logRequest({
  gelf: gelf,
  transformers: [
    (req, res, event) => {
      if (req.session) {
        // Modify the event
        event.memberID(req.session.userID);
      }

      // Whatever you return will be passed
      // to the next transformer/send to Graylog.
      return event;
    }
  ]
});

Development

Local setup

If you want to use/test your changes locally, link the package using npm, and then install the linked package in your service:

$ cd ~/graylog-gelf
$ npm link
$ cd ~/your-service
$ npm link @trackcode/gelf

This will install the dependency locally, using the current content of your dist/ (build output) folder.

To continously update the package with new changes from src/, run npm run build:watch in the project folder, and restart your service after every change.

Tests

Tests are built with Jest and can be run like this:

npm run test