@elastic/ecs-helpers

A set of helpers for the ECS logging libraries. You should not directly used this package, but the ECS logging libraries instead.

Install

npm install @elastic/ecs-helpers

API

version

The currently supported version of Elastic Common Schema.

stringify

Function that serializes (very quickly!) an ECS-format log record object.

const { stringify } = require('@elastic/ecs-helpers')
const ecs = {
  '@timestamp': new Date().toISOString(),
  'log.level': 'info',
  message: 'hello world',
  log: {
    logger: 'test'
  },
  ecs: {
    version: '1.4.0'
  }
}

console.log(stringify(ecs))

Note: This uses fast-json-stringify for serialization. By design this chooses speed over supporting serialization of objects with circular references. This generally means that ecs-logging-nodejs libraries will throw a "Converting circular structure to JSON" exception if an attempt is made to log an object with circular references.

formatError(obj, err) -> bool

A function that adds ECS Error fields for a given Error object. It returns true iff the given err was an Error object it could process.

const { formatError } = require('@elastic/ecs-helpers')
const logRecord = { msg: 'oops', /* ... */ }
formatError(logRecord, new Error('boom'))
console.log(logRecord)

will show:

{
  msg: 'oops',
  error: {
    type: 'Error',
    message: 'boom',
    stack_trace: 'Error: boom\n' +
      '    at REPL30:1:26\n' +
      '    at Script.runInThisContext (vm.js:133:18)\n' +
      // ...
  }
}

The ECS logging libraries typically use this to automatically handle an err metadata field passed to a logging statement. E.g. log.warn({err: myErr}, '...') for pino, log.warn('...', {err: myErr}) for winston.

formatHttpRequest(obj, req) -> bool

Function that enhances an ECS object with http request data. The given request object, req, must be one of the following:

• Node.js's core http.IncomingMessage,
• Express's request object that extends IncomingMessage, or
• a hapi request object.

The function returns true iff the given req was a request object it could process. Note that currently this notably does not process a http.ClientRequest as returned from http.request().

const http = require('http')
const { formatHttpRequest } = require('@elastic/ecs-helpers')

http.createServer(function (req, res) {
  res.end('hi')

  const obj = {}
  formatHttpRequest(obj, req)
  console.log('obj:', JSON.stringify(obj, null, 4))
}).listen(3000)

Running this and making a request via curl http://localhost:3000/ will print something close to:

obj: {
    "http": {
        "version": "1.1",
        "request": {
            "method": "get",
            "headers": {
                "host": "localhost:3000",
                "accept": "*/*"
            }
        }
    },
    "url": {
        "full": "http://localhost:3000/",
        "path": "/"
    },
    "client": {
        "address": "::1",
        "ip": "::1",
        "port": 61969
    },
    "user_agent": {
        "original": "curl/7.64.1"
    }
}

formatHttpResponse(obj, res)

Function that enhances an ECS object with http response data. The given request object, req, must be one of the following:

• Node.js's core http.ServerResponse,
• Express's response object that extends ServerResponse, or
• a hapi request object

The function returns true iff the given res was a response object it could process. Note that currently this notably does not process a http.IncomingMessage that is the argument to the "response" event of a client http.request()

const http = require('http')
const { formatHttpRequest } = require('@elastic/ecs-helpers')

http.createServer(function (req, res) {
  res.setHeader('Foo', 'Bar')
  res.end('hi')

  const obj = {}
  formatHttpResponse(obj, res)
  console.log('obj:', JSON.stringify(obj, null, 4))
}).listen(3000)

Running this and making a request via curl http://localhost:3000/ will print something close to:

rec: {
    "http": {
        "response": {
            "status_code": 200,
            "headers": {
                "foo": "Bar"
            }
        }
    }
}

License

This software is licensed under the Apache 2 license.