# @trackcode/gelf

> GELF HTTP Libray

Latest version **0.4.4** (published 2021-04-07) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install @trackcode/gelf
pnpm add @trackcode/gelf
yarn add @trackcode/gelf
bun add @trackcode/gelf
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.4 |
| Published | 2021-04-07 |
| First published | 2019-04-09 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 42.2 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Julian Tölle |
| Maintainers | nschnierer, apricote |

## Links

- npm: https://www.npmjs.com/package/@trackcode/gelf
- npm.io page: https://npm.io/package/@trackcode/gelf

## Dependencies (4)

- [debug](https://npm.io/package/debug.md) ^4.1.1
- [request](https://npm.io/package/request.md) ^2.88.0
- [response-time](https://npm.io/package/response-time.md) ^2.3.2
- [request-promise-native](https://npm.io/package/request-promise-native.md) ^1.0.7

## Recent versions

- 0.4.4 (latest) — 2021-04-07
- 0.4.3 — 2020-02-25
- 0.4.2 — 2019-08-05
- 0.4.1 — 2019-05-27
- 0.3.1 — 2019-05-27
- 0.4.0 — 2019-04-30
- 0.3.0 — 2019-04-16
- 0.2.0 — 2019-04-15
- 0.1.0 — 2019-04-09

## README

# @trackcode/gelf

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

## Usage

Install the package:

```shell
npm i @trackcode/gelf
```

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

```javascript
// 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:

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

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

```javascript
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:

```javascript
gelfEndpoint: "https://username:password@graylog.example.com/gelf";
```

### Emitting Events

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

```javascript
// 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`](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`](src/events) folder. They expose a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface) to set the values.

```javascript
// 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](#using-typed-events) to learn more).

```javascript
// 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:

```javascript
// 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:

```shell
$ 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:

```shell
npm run test
```

---
_Source: https://npm.io/package/@trackcode/gelf · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._