Notoriously Pedantic Magistrate

    dogear

    5.0.0 • Public • Published

    Dogear

    Build Status Current Version

    A hapi plugin for sending request round trip metrics and server ops metrics to a statsd-compliant service (Datadog, InfluxDB's Telegraf, etc) and also exposes an expanded statsd client to the server.

    This plugin started life as a fork of hapi-statsd and has evolved since then. Thanks to Mac Angell for his hard work on hapi-statsd!

    NOTE:

    • Dogear 5.x.x works with the namespaced versions of hapi 19 and greater (@hapi/hapi) and requires node v12 or greater.
    • Dogear 4.x.x works with the namespaced versions of hapi 17 and greater (@hapi/hapi).
    • Dogear 3.x.x works with hapi 17 and above.
    • Dogear 2.x.x works with earlier versions.

    Install

    $ npm install --save dogear
    #or 
    $ yarn add dogear

    Usage

    To install this plugin on your hapi server, do something similar to this:

    const hapi = require('@hapi/hapi');
    const server = new hapi.Server();
     
    const dogearOptions = {}
     
    await server.register({
      plugin: require('dogear'),
      options: dogearOptions
    });
     
    await server.start();

    Configuration

    The plugin accepts multiple optional configuration parameters to customize its behavior.

    statsdConfig

    Optional initialization parameters for the statsd client:

    • host - The host to send stats to default: localhost
    • port - The port to send stats to default: 8125
    • prefix - What to prefix each stat name with default: 'hapi.'
    • suffix - What to suffix each stat name with default: ''
    • globalize - Expose this StatsD instance globally? default: false
    • cacheDns - Cache the initial dns lookup to host default: false
    • mock - Create a mock StatsD instance, sending no stats to the server? default: false
    • globalTags - Tags that will be added to every metric default: []
    • maxBufferSize - If larger than 0, metrics will be buffered and only sent when the string length is greater than the size. default: 0
    • bufferFlushInterval - If buffering is in use, this is the time in ms to always flush any buffered metrics. default: 1000
    • telegraf - Use Telegraf's StatsD line protocol, which is slightly different than the rest default: false
    • errorHandler - A function with one argument. It is called to handle various errors. default: none, errors are thrown/logger to console

    opsInterval

    How often the server will send operational stats. Defaults to 1000. If set to null or <= 0, the plugin will not report operational metrics.

    opsMetrics

    An array of strings represeting the operational metrics to report. Allowed values:

    • os.load.1 - One minute average of server CPU load
    • os.load.5 - Five minute average of server CPU load
    • os.load.15 - Fifteen minute average of server CPU load
    • proc.uptime - Uptime for hapi server process
    • proc.mem.rss - Amount of memory set aside for hapi server process (Learn More)
    • proc.mem.heapTotal - Heap memory allocated for hapi server process
    • proc.mem.heapUsed - Heap memory used by hapi server process
    • proc.delay - Current event queue delay

    Defaults to an array containing all the above.

    Example

    A hapi route configured like this:

    server.route({
      method: 'GET',
      path: '/test/{param}',
      handler: () => 'Success!'
    });

    would send increment stats to statsd with the following names:

    hapi.request.status.200
    hapi.request.received
    

    and a timing stat named:

    hapi.request.response_time
    

    if the statsd server supports tags, it will also receive the following tags (in addition to any global tags):

    path:/test/{param}
    method:GET
    status:200
    

    As the statsd client is also exposed to the hapi server, you can use any of its methods, e.g.:

    server.statsd.increment('systemname.subsystem.value');
    server.statsd.gauge('what.you.gauge', 100);
    server.statsd.set('your.set', 200);
    server.statsd.histogram('timing.metric', 235, [ 'tags' ]);

    Version Compatibility

    • Version 5: @hapi/hapi 19.x.x and higher on Node 12
    • Version 4: @hapi/hapi 17.x.x and higher
    • Version 3: Currently tested with hapi 17.x.x on Node 8
    • Version 2: Up to hapi 16.x.x

    License

    This project is licensed under the MIT license. See the LICENSE file for more info.

    Install

    npm i dogear

    DownloadsWeekly Downloads

    562

    Version

    5.0.0

    License

    MIT

    Unpacked Size

    10.6 kB

    Total Files

    5

    Last publish

    Collaborators

    • pizzabrandon