stash-optimise

Stash

A zero-dependency npm library to quickly connect to the Optimise LogStash instance and send your log lines!

Installing

npm install stash-optimise

Import

The library exports a stash object, which is a pre-initialised instance of StashInstance.

Importing:

import { stash } from 'stash'

or

const stash = require('stash').stash

Environment variables

• LOGSTASHHOST (Required) - the URL of the logstash instance to send logs to
• ENVIRONMENT (Optional) - a default value for log environment properties. e.g. prod

Usage

The library exports one method, Send, and this takes a Log object to be sent. An example usage might be

stash.Send({
	category: 'info',
	tags: [ 'insights', 'api', 'security.authentication', 'login' ],
	message: 'Bad login attempt',
	data: {
		userId: 4434,
		agencyId: 1
	},
	stacktrace: err.stack
})

Send is an async function and can be awaited to retrieve a ConcreteLog, which is the same as a Log but also includes timestamp, id and environment information.

The category, tags, and message properties are required, but data, and stacktrace are optional. The log will automatically populate environment information from the ENVIRONMENT environment variable, but this can be overridden with the log property environment.

Usage of IDs

Because each generated log message has a UUID, it might be desirable to pass this value back from the API - a user can report error IDs back to developers, and developers can use these IDs to see the contents of a log message. For example:

} catch (err) {
	const log = await stash.Send({
		category: 'minor',
		tags: [ 'insights', 'api', 'notification.alert' ],
		message: 'Tried to create an alert for an invalid user ID',
		stacktrace: err.stack
	})

	res.send(400, {
		message: 'Tried to create an alert for an invalid user ID',
		errorId: log.id
	})
}

Command-line tool

After installing globally (-g), the tool stash will be added to your PATH. The same tool is available at node_modules/.bin/stash anywhere you have installed stash as a dependency. The tool can be used to send JSON directly to logstash like so:

echo '{ "environment": "foo", "message": "test", "tags": ["test"] }' | stash

Be sure to have your LOGSTASHHOST environment variable set, or the command will fail.

Building / Contributing

This project uses TypeScript, and exports TypeScript types. To do any development work, simply npm install to get dependencies and npm run build to build with your changes. Development uses a local version of tsc, so this is managed for you.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.