@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:
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:
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.