Navy Penguin Mariachi

    stash-optimise
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    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.

    Keywords

    none

    Install

    npm i stash-optimise

    DownloadsWeekly Downloads

    18

    Version

    1.0.2

    License

    UNLICENSED

    Unpacked Size

    6.87 kB

    Total Files

    10

    Last publish

    Collaborators

    • matthew.knights
    • ale770