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 await
ed 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.