CONTRIBUTING.md

How to contribute to newrelic browser exporter

Table of Contents

Project structure

• application
• plugins

How to set up a new metric

Tests

Project structure

application:

─ src/
  ├── app/
  │   ├── routes/
  │   │   └── metrics.js
  │   ├── router.js
  │   └── server.js
  └── index.js

src/app/routes/metrics.js - It represents the /metrics route, which outputs the metrics from register.metrics() as a string in a Prometheus like format that can be consumed by a Prometheus Client.

src/app/router.js - It registers all application routes.

src/app/server.js - Contains the code to start and configure the application.

src/index.js - It starts the application.

plugins:

─ src/
  └── plugins/
      ├── newrelic_browser/
      │   ├── javascriptErrorsPercent/
      │   └── api-request.js
      └── prometheus/
          └── charts/
              ├── default.js
              └──  gauge.js

newrelic_browser/ - This plugin is responsible for pulling data from New Relic's API(api-request.js) and exporting it as Prometheus charts.

prometheus - Contains the metric types used to create new Prometheus charts and exports the global Prometheus registry. To know which metrics are supported by Prometheus, see metric types.

How to set up a new metric

Create a new folder inside newrelic_browser plugin. Inside this folder create a new file that must have a public method called collectData which must return a new Promise. The public method initializes and returns the chart:

// javascriptErrorsPercent.js
const GaugeChart = require('../../prometheus/charts/gauge');
let JSErrorsGauge;

const collectData = () => new Promise((resolve, reject) => {
  if (!JSErrorsGauge) {
    JSErrorsGauge = new GaugeChart({
      name: 'newrelic_browser_javascript_errors_percent',
      help: 'return a percentage of pageviews with javascript errors',
    });
  }

  ...
}

module.exports = {
  collectData,
};

Please take a look at Prometheus best practices to learn how to set up a chart's configurations properly.

After configuring the chart, it is necessary to set up parameters such as name and value to retrieve specific metrics from New Relic's API

// javascriptErrorsPercent.js
const collectData = () => new Promise((resolve, reject) => {
  ...

  const names = 'EndUser/errors';
  const values = 'error_percentage';

  ...
}

Now that all parameters are set up, a request to New Relic's API can be done by calling browser.collectData():

// javascriptErrorsPercent.js
const browser = require('../api-request');

const collectData = () => new Promise((resolve, reject) => {
  //...

  browser
    .collectData(names, values)
    .then(response => {
      onSuccess(response, resolve);
    })
    .catch(reject);

}
//...

A callback method should set the metrics collected from New Relic's API into the chart. Please, see prometheus base units to know how to set values into charts according Prometheus patterns.

// javascriptErrorsPercent.js
function onSuccess(response, resolve) {
  const percentage = JSON.parse(response)
    .metric_data.metrics[0]
    .timeslices[0]
    .values
    .error_percentage / 100;

  JSErrorsGauge.setValues(Number(percentage.toFixed(8)));
  resolve();
}
//...

After setting values to the chart and resolving the Promise, New Relic's metrics are avaliable as Prometheus metrics in the /metrics endpoint.

Tests

Tests are written using jest. In most cases new test scenarios are necessary for the new developed code.

Run tests using jest or npm test commands. To see coverage, run jest --coverage.