@madgex/datadog-monitoring

Madgex Datadog Logging and Monitoring

All your Hapi + Datadog needs, in one handy package.

Install

npm install @madgex/datadog-monitoring

Install peer dependencies alongside:

npm install hot-shots dd-trace

Exports

Path	Exports
@madgex/datadog-monitoring	trace, pino, autoLogErrors
@madgex/datadog-monitoring/statsd	plugin, addToVisionContext
@madgex/datadog-monitoring/utils	getAWSAgent

Usage

Tracing

The tracer must be initialised before requiring Hapi to correctly instrument the APM.

const { trace } = require('@madgex/datadog-monitoring');

const tracer = await trace({
  hostname: DD_AGENT_HOSTNAME || '',
  service: 'my-service-name',
  hapiOptions: { blacklist: ['/healthcheck'] },
});

hostname, if not set, defaults to the discoverable Datadog agent host on AWS. All dd-trace Hapi plugin options can be passed as hapiOptions. The returned tracer instance allows further plugin configuration.

Logging

const { pino, autoLogErrors } = require('@madgex/datadog-monitoring');

await server.register([
  { plugin: pino, options: { level: LOG_LEVEL, redact: ['req.headers.authorization'] } },
  { plugin: autoLogErrors, options: { level: LOG_LEVEL, threshold: 399 } },
]);

• level — log level, defaults to 'info'
• threshold — status code above which to log as 'warn', defaults to 399

StatsD

const { plugin } = require('@madgex/datadog-monitoring/statsd');

await server.register({
  plugin,
  options: {
    host: DD_AGENT_HOSTNAME,  // required
    mock: false,              // default
    // all hot-shots options are passed through:
    port: 8125,
    prefix: 'myapp.',
    globalTags: ['env:production'],
  },
});

host is required. On AWS, use getAWSAgent() to discover the agent hostname:

const { getAWSAgent } = require('@madgex/datadog-monitoring/utils');
const host = await getAWSAgent();

The plugin decorates both server and request with a statsDClient:

server.statsDClient.increment('page.view', 1, ['route:home']);
request.statsDClient.histogram('api.latency', responseTime);

See hot-shots docs for supported options and methods.

Manifest.js (hapipal/boilerplate + haute-couture)

If you use hapipal/boilerplate, pass statsd options to your main ../lib plugin in manifest.js, then wire a loader in lib/plugins/statsd.js.

// server/manifest.js
register: {
  plugins: [
    {
      plugin: '../lib',
      options: {
        statsd: {
          host: {
            $filter: { $env: 'NODE_ENV' },
            test: {
              $env: 'DD_AGENT_HOSTNAME',
              $default: 'localhost',
            },
            $default: {
              $env: 'DD_AGENT_HOSTNAME',
              $default: null,
            },
          },
          port: {
            $env: 'DD_AGENT_DSTATS_PORT',
            $coerce: 'number',
            $default: 8125,
          },
          mock: {
            $filter: { $env: 'NODE_ENV' },
            $default: true,
            production: false,
          },
          prefix: 'my_service_',
        },
      },
    },
  ],
}

// lib/plugins/statsd.js
const { plugin } = require('@madgex/datadog-monitoring/statsd');
const { getAWSAgent } = require('@madgex/datadog-monitoring/utils');

module.exports = async (_server, incomingOptions) => {
  const options = { ...incomingOptions?.statsd };

  if (!options.host && !options.mock) {
    options.host = await getAWSAgent();
  }

  return { plugin, options };
};

This keeps metrics calls simple (server.statsDClient / request.statsDClient always decorated) while only sending metrics when mock is false.

Template metrics with addToVisionContext

addToVisionContext adds metric.increment, metric.histogram, and metric.timing to template context. Each returns '' for safe inline usage.

const { addToVisionContext } = require('@madgex/datadog-monitoring/statsd');

// In your view-manager / vision context function:
context = addToVisionContext(request, context);

In Nunjucks templates:

{{ metric.increment('page.rendered', ['theme:dark']) }}
{{ metric.timing('widget.load', loadTimeMs) }}

CLI

Pipe Pino logs from stdout to a Datadog agent over UDP:

"start": "dd-monitor /path/to/server.js --hostname [hostname] --port [port]"

Flags: --hostname/-h, --port/-p (required), --echo/-e, --debug/-d. Do not enable echo/debug in production.

Migrate statsd from pre-v6 versions of @madgex/datadog-monitoring

1. Install peers

npm install hot-shots dd-trace

2. Update imports

- const { statsDClient, trace, pino, autoLogErrors } = require('@madgex/datadog-monitoring');
+ const { trace, pino, autoLogErrors } = require('@madgex/datadog-monitoring');
+ const { plugin: statsdPlugin } = require('@madgex/datadog-monitoring/statsd');

If you import getAWSAgent from an internal path, switch to the public export:

- const { getAWSAgent } = require('@madgex/datadog-monitoring/src/utils');
+ const { getAWSAgent } = require('@madgex/datadog-monitoring/utils');

3. Update plugin options

  await server.register({
    plugin: statsdPlugin,
    options: {
-     DD_AGENT_HOSTNAME: hostname,
-     DD_AGENT_DSTATS_PORT: port,
+     host: hostname,  // required
+     port: port,
      mock: false,
    },
  });

host is now required — the plugin no longer falls back to AWS metadata. Call getAWSAgent() yourself if needed.

4. Template metrics (optional)

If you have a custom nunjucks.addGlobal('metric', ...), replace it with addToVisionContext:

- nunjucks.addGlobal('metric', function (name, ...args) {
-   const request = this.ctx.request;
-   if (request && request.statsDClient) {
-     try { request.statsDClient.increment(name, ...args); }
-     catch (err) { /* ... */ }
-   }
-   return '';
- });

+ const { addToVisionContext } = require('@madgex/datadog-monitoring/statsd');
+ // In your vision context function:
+ context = addToVisionContext(request, context);

Templates change from {{ metric('name', ['tag']) }} to {{ metric.increment('name', ['tag']) }}.

Development

Tests

npm test
npm run test:integration

Linting

npm run lint