Necessitates Proper Modularity

    @trackcode/gelf
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.4 • Public • Published

    @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:password@graylog.example.com/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

    Keywords

    none

    Install

    npm i @trackcode/gelf

    DownloadsWeekly Downloads

    16

    Version

    0.4.4

    License

    UNLICENSED

    Unpacked Size

    43.3 kB

    Total Files

    43

    Last publish

    Collaborators

    • nschnierer
    • apricote