@adobe/openwhisk-newrelic v2.0.0

node-openwhisk-newrelic

Library for gathering metrics from Apache OpenWhisk actions and sending them to New Relic Insights.

NewRelic Insert API JSON format guidelines

Reference: https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/send-custom-events-event-api

• eventType required
• timestamp Unix epoch timestamp either in seconds or milliseconds
• Key-value pairs with float and string values only
• Limits:
  • 255 attributes
  • 255 characters in the attribute name
  • 100 character length limit of individual string values (NR supports 4k but this library will truncate long strings automatically and add an ellipsis.)
  • 1500 character length for error metric strings by default, or configurable by setting the NEW_RELIC_ERROR_METRIC_MAX_STRING_LENGTH environment variable
  • 100,000 HTTP POST requests/min, 429 status after, counter reset of 1 minute window

Usage

From New Relic you will need:

• your account id
• your New Relic Insights API key (note the "Insights" here, it's separate from a plain NR api key)

Initialize the New Relic Metrics agent with those values. You typically want to do that right when your action starts in order to get action timeout metrics or support automatic instrumentation (see below).

const { NewRelic } = require('@adobe/openwhisk-newrelic');
const metrics = new NewRelic({
    newRelicEventsURL: 'https://insights-collector.newrelic.com/v1/accounts/<YOUR_ACOUNT_ID>/events',
    newRelicApiKey: 'YOUR_INSIGHTS_API_KEY'
});

Then collect all your custom/background metrics in a separate object

const customMetrics = {
    data: "value",
    userName: "sampleUser"
}

Send your metrics to New Relic:

await metrics.send('EVENT_TYPE', customMetrics);

Note that metrics are not sent immediately but are collected in the background and sent in intervals every 10 seconds by default. This can be configured via sendIntervalMs in the options of the constructor (in milliseconds).

Also note that new NewRelic() will start a setTimeout that will send metrics if your action is close to timeout using __OW_DEADLINE.

You MUST call activationFinished() to stop the agent when you are done sending metrics, or when your action is finishing. This will clear the action timeout that began when the class instance was defined.

metrics.activationFinished();

To disable all sending of metrics to New Relic (for example in unit tests), set this environment variable:

OPENWHISK_NEWRELIC_DISABLE_METRICS=true

Instrumentation

Supported instrumentation:

• http requests (outgoing requests, via the node http and https modules):
  • reference documentation
  • on by default
  • can be disabled with environment variable: OPENWHISK_NEWRELIC_DISABLE_HTTP_INSTRUMENTATION=true
  • can also be disabled by setting disableHttpClient: true in the options passed to NewRelic.instrument()

To enable instrumentation, wrap the action main function in NewRelic.instrument(). A complete example might look like this:

async function main(params) {
    const metrics = new NewRelic({
        newRelicEventsURL: 'https://insights-collector.newrelic.com/v1/accounts/<YOUR_ACOUNT_ID>/events',
        newRelicApiKey: 'YOUR_INSIGHTS_API_KEY'
    });
    try {
        // do something
    } finally {
        metrics.activationFinished();
    }
}

exports.main = NewRelic.instrument(main);

To disable all instrumentation (for example in unit tests), set this environment variable:

OPENWHISK_NEWRELIC_DISABLE_ALL_INSTRUMENTATION=true

Action Timeout

The default behavior of the agent is it will begin a setTimeout that will send metrics right before the action times out, using the OW_DEADLINE environment variable.

In case you want to opt out of the action timeout, (example: unit tests) there are two ways to opt out:

1. Pass in disableActionTimeout to options:

   const metrics = new NewRelic({
       newRelicEventsURL: 'https://insights-collector.newrelic.com/v1/accounts/<YOUR_ACOUNT_ID>/events',
       newRelicApiKey: 'YOUR_INSIGHTS_API_KEY',
       disableActionTimeout: true
   });

2. Set the environment variable: DISABLE_ACTION_TIMEOUT_METRIC to true:

   export DISABLE_ACTION_TIMEOUT_METRIC = true

If either of these are set to true, there will be no action timeout and calling activationFinished is no longer necessary.

In case you want to pass custom metrics to the action timeout, you can define a callback function in New Relic options. The result of the callback will be added to the default metrics and sent at action timeout. If you do not define an eventType, it will default to timeout.:

const metrics = new NewRelic({
    newRelicEventsURL: 'https://insights-collector.newrelic.com/v1/accounts/<YOUR_ACOUNT_ID>/events',
    newRelicApiKey: 'YOUR_INSIGHTS_API_KEY',
    actionTimeoutMetricsCb: function () {
        return {
            eventType: 'error',
            ...customMetrics
        }
    }
});

Standard

Sent for all metrics.

Http

Tracks each outgoing http request. Automatically instrumented in node and done in all actions.

Naming is aligned with NewRelic's standard SyntheticRequest attributes.

Event type: http

Contributing

Contributions are welcomed! Read the Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. See LICENSE for more information.