Monitorado

A simple but effective library to track app metrics.

Basic usage

const monitorado = require("monitorado")

try {
    // Start a metric to calculate how long the DB cleanup takes...
    let mt = monitorado.start("db-cleanup")

    // Cleanup database...
    await myApp.cleanupDatabase()

    // End db-cleanup metric.
    mt.end()

} catch (ex) {
    // End metric with error.
    mt.end(ex)
}

// Get metrics output.
let output = monitorado.output()

// Last 1 minute metrics for db-cleanup...
console.dir(output["db-cleanup"].last_1min)

More features

for (let i = 0; i < 100; i++) {

    // Auto expire counter after 5 seconds.
    let expiringMt = monitorado.start("timeout-method", {expiresIn: 5000})
    await myApp.externalCall()

    // If externalCall takes more than 5 sec, counter will auto-expire
    // so calling .end() won't do anything.
    expiringMt.end()
}

// Create metric with a tag.
let anotherMt = monitorado.start("user-method", {tag: "Users"})
let result = await myApp.getUserStats()

// Add extra data to metric, for instance a user count.
anotherMt.setData("users", result.users)
anotherMt.end()

// Output metrics for timeout-method only, for the last 1, 2, and 5 minutes.
const outputOptions = {intervals: [1, 2, 5], keys:  ["timeout-method"]}
let timeoutOutput = monitorado.output(outputOptions)

Built-in HTTP server

try {
    // Set a custom port and base path.
    monitorado.settings.httpServer.port = 8080
    monitorado.settings.httpServer.path = "/metrics"

    // Or you can also load and manipulate settings directly via SetMeUp...
    const setmeup = require("setmeup")
    setmeup.load("settings.monitorado.json")

    // Start the built-in HTTP server
    monitorado.httpServer.start()
    // Calling http://your-host:8080/metrics will output the metrics.

    // You can also protect the endpoint with a token.
    monitorado.settings.httpServer.token = "my-custom-token"
    // Now you need to pass an Authorization: Bearer my-customer-token header.
}

Persisting metrics

try {
    // Save current finished metrics to the monitorado.json file.
    monitorado.metrics.saveTo()

    // You can also specify a different file path.
    monitorado.metrics.saveTo("/usr/data/monitorado.json")

    // Or simply get the exported JSON as as object.
    let data = monitorado.metrics.toJSON()
    // Send data above to an external storage, S3, etc...

    // Now load metrics from an exported file.
    monitorado.metrics.loadFrom("/usr/data/monitorado.json")

    // Or load from an exported object directly. For example, download JSON data from S3.
    let s3data = myS3.downloadFile("monitorado.json")
    monitorado.metrics.loadFrom(s3data)

    // You can also avoid loading metrics that already exists in memory by using avoidDuplicates = true.
    monitorado.metrics.loadFrom(s3data, true)
}

Default settings

In a nutshell, the default settings contains all the defaults used by Monitorado. You can override settings by creating a settings.json on the root of your app, or programatically by changing values directly on the monitorado.settings object.

Monitorado uses SetMeUp to manage its settings, so you might want to take a look there for some insights and how to define your custom settings.

Sample output

Below you'll find a sample output generated by Monitorado for a sample app, with comments added for reference:

{
    // Some system metrics taken from jaul.system.getInfo()
    "system": {
        "loadAvg": 1,
        "memoryUsage": 61
    },
    // Metrics for "ad.fetch"
    "ad.fetch": {
        "total_calls": 930, // total number of calls currently recorded
        // Following counters are for the last 1 minute...
        "last_1min": {
            "calls": 17, // 17 calls
            "errors": 0, // 0 calls with errors
            "expired": 1, // 1 expired calls
            "min": 305, // minimum elapsed time 305ms
            "max": 399, // maximum elapsed time 399ms
            "avg": 373, // average elapsed time of 373ms
            "p99": 399, // 99 percentile 399ms
            "p90": 385 // 90 percentile 385ms
        },
        // The following counters are for the last 20 minutes...
        "last_20min": {
            "calls": 840,
            "errors": 2,
            "expired": 1,
            "min": 305,
            "max": 970,
            "avg": 391,
            "p99": 399,
            "p90": 390,
            // Extra data appended to counters on last 20 minutes,
            // for example mt.setData("users", 35).
            "data": {
                "users": {
                    "min": 35,
                    "max": 35,
                    "total": 35
                }
            }
        }
    },
    // Same as above, for for "google.fetch"...
    "google.fetch": {
        "total_calls": 1410,
        "last_1min": {
            "calls": 19,
            "errors": 0,
            "expired": 0,
            "min": 2100,
            "max": 3755,
            "avg": 2900,
            "p99": 3755,
            "p90": 2920
        },
        "last_20min": {
            "calls": 1403,
            "errors": 0,
            "expired": 0,
            "min": 2008,
            "max": 3940,
            "avg": 2974,
            "p99": 3001,
            "p90": 2976
        }
    }
}

On the sample above, the first system key is shown because the systemMetrics setting has key = "system and fields "loadAvg" and "memoryUsage". For the list of available fields, please check the SystemMetrics interface from JAUL.

Each of the next keys "ad.fetch" and "google.fetch" represent a specific metric. The settings intervals for the above sample is set to "[1, 20]". The setting percentiles is "[99, 90]".

Please note that the total_calls for a particular metric can be higher than the calls for the highest interval shown on the output. The total_calls simply tells us how many counters are currently stored for that metric, and is directly dependant on the expireAfter setting.

API documentation

You can browse the full API documentation at https://monitorado.devv.com.