Write synthetic API tests (legacy runtime - Node.js 10 and lower)

Important

As of August 26, 2024, you can no longer create new monitors using legacy runtimes on public or private locations. On October 22, 2024, we will end of life the containerized private minion (CPM) and legacy synthetics runtime versions.

For public locations, use the runtime upgrade UI to update your monitors to the newest runtimes.
For private locations, please review our recommended migration steps to avoid monitor degradation.

Use synthetic monitoring's API tests to monitor your API endpoint to ensure it is functioning correctly. New Relic uses the http-request module internally to make HTTP calls to your endpoint and validate the results.

Please refer to the [Node 16.10 or newer API runtime examples](Details for the writing scripts Node 16.10 runtime to create monitors using our latest synthetics runtimes.

Here we present some example functions showing how to use the $http object to submit your request. For detailed documentation on the options available for this object, see the http-request readme. (Note that Request is deprecated, but these options still apply.)

Tip

To view and share other API test examples, visit the Support Forum synthetics scripts section or the Synthetic monitoring quickstarts library.

Use API http-request module

API tests are powered by the http-request module, which is available through the $http object. Once each frequency interval, New Relic queries your endpoint from each of your selected locations. For instructions on creating a monitor, see Adding monitors.

Read on to learn how to define metadata for your request, make a GET request, make a POST request, and how to validate the results.

Important

After a maximum run time of three minutes, New Relic manually stops the script.

one.newrelic.com > Synthetic monitoring > Create monitor: The script editor suggests functions, selectors, and other elements to simplify scripting commands (available in GitHub).

Configure request options

To start your script:

Declare a variable (such as options) to store your request options object.
Define request options such as the URL endpoint, and custom headers.
If you're setting SSL or agent options, see SSL and agentOptions requirements. We recommend using SSL to avoid exposing plain text credentials in your headers.

Tip

For a full list of supported request options, see request(options, callback) in the http-request documentation on GitHub.

Here's an example of optional metadata in the options object:

// Declare optional metadata
var options = {
  // Specify the endpoint URL
  url: "https://api-endpoint.example.com",
  // Specify optional headers
  headers: {
    "Endpoint-Key": "YOUR_ENDPOINT_KEY",
    "Additional-Header": "Additional-Header-Data",
  },
};

For SSL and agentOptions: If you are setting SSL options or providing an agentOptions object, the agent property in the request options object will need to be set to $globalAgents.https or $globalAgents.http to ensure your HTTP requests use the instrumented global agent.

Here's an example of using a SSL option or agentOptions:

This example uses agentOptions:

// Declare optional metadata
var options = {
  // Specify the endpoint URL
  url: "https://api-endpoint.example.com",
  // Specify optional headers
  headers: {
    "Endpoint-Key": "YOUR_ENDPOINT_KEY",
    "Additional-Header": "Additional-Header-Data",
  },
  // Specify global agent as the http agent
  agent: $globalAgents.https,
  // Set SSL option
  strictSSL: true,
  // Specify http agent options
  agentOptions: {
    maxVersion: "TLSv1.1",
  },
};

Send a GET request

To make a GET request, use the $http.get method to submit your request. Define your request options, make your request using $http.get, then validate the response to ensure your endpoint is returning the correct results.

Send a POST request

To make a POST request, use the $http.post method to submit your request. Define your request options, make your request using $http.post, then validate the response to ensure your endpoint is returning the correct results.

This example queries our NerdGraph API:

// Define your authentication credentials
const myAccountId = "YOUR_ACCOUNT_ID";
const myAPIKey = "YOUR_LICENSE_KEY";

const options = {
  // Define endpoint URI, https://api.eu.newrelic.com/graphql for EU accounts
  uri: "https://api.newrelic.com/graphql",
  headers: {
    "API-key": myAPIKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
          query getNrqlResults($accountId: Int!, $nrql: Nrql!) {
            actor {
              account(id: $accountId) {
                nrql(query: $nrql) {
                  results
                }
              }
            }
          }
        `,
    variables: {
      accountId: Number(myAccountId),
      nrql: "SELECT average(duration) FROM Transaction",
    },
  }),
};

// Define expected results using callback function
function callback(err, response, body) {
  // Log JSON results from endpoint to Synthetics console
  console.log(JSON.parse(body));
  console.log("Script execution completed");
}

// Make POST request, passing in options and callback
$http.post(options, callback);

This example POSTs a custom event containing static integers to the Event API:

// Define your authentication credentials.
var myAccountID = "YOUR_ACCOUNT_ID";
var myLicenseKey = "YOUR_LICENSE_KEY";
// Import the 'assert' module to validate results: https://nodejs.org/docs/latest/api/assert.html
var assert = require("assert");

var options = {
  // Define endpoint URL.
  url: "https://insights-collector.newrelic.com/v1/accounts/" + myAccountID + "/events",
  // Define body of POST request.
  body: '[{"eventType":"SyntheticsEvent","integer1":1000,"integer2":2000}]',
  // Define New Relic license key and expected data type.
  headers: {
    "Api-Key": myLicenseKey,
    "Content-Type": "application/json",
  },
};

// Define expected results using callback function.
function callback(error, response, body) {
  // Log status code to Synthetics console.
  console.log(response.statusCode + " status code");
  // Verify endpoint returns 200 (OK) response code.
  assert.ok(response.statusCode == 200, "Expected 200 OK response");
  // Parse JSON into variable.
  var info = JSON.parse(body);
  // Verify that `info` contains element named `success` with a value of `true`.
  assert.ok(
    info.success == true,
    "Expected True results in Response Body, result was " + info.success
  );
  // Log end of script.
  console.log("End reached");
}

// Make POST request, passing in options and callback.
$http.post(options, callback);

Validate results

To validate your results, import the assert module to define your test case. Call an assert method to validate your endpoint's response. If any assert functions fail, the entire monitor will be considered a failed check. This may trigger alert notifications and affect your metrics.

Important

Synthetic monitoring does not allow thrown exceptions. Thrown exceptions result in script failure. Use the assert module to validate your results, and use console.log() to log results to the synthetic's console.

This example POSTs to the Event API, then validates that the response is {"success":true}:

// Define your authentication credentials.
var myAccountID = "YOUR_ACCOUNT_ID";
var myLicenseKey = "YOUR_LICENSE_KEY";
// Import the `assert` module to validate results.
var assert = require("assert");

var options = {
  // Define endpoint URL.
  url: "https://insights-collector.newrelic.com/v1/accounts/" + myAccountID + "/events",
  //Define body of POST request.
  body: '[{"eventType":"SyntheticsEvent","integer1":1000,"integer2":2000}]',
  // Define New Relic license key and expected data type.
  headers: {
    "Api-Key": myLicenseKey,
    "Content-Type": "application/json",
  },
};

$http.post(options, function (error, response, body) {
  // Log status code to Synthetics console. The status code is logged before the `assert` function,
  // because a failed assert function ends the script.
  console.log(response.statusCode + " status code");
  // Call `assert` method, expecting a `200` response code.
  // If assertion fails, log `Expected 200 OK response` as error message to Synthetics console.
  assert.ok(response.statusCode == 200, "Expected 200 OK response");
  var info = JSON.parse(body);
  // Call `assert` method, expecting body to return `{"success":true}`.
  // If assertion fails, log `Expected True results in Response Body,` plus results as error message to Synthetics console.
  assert.ok(
    info.success == true,
    "Expected True results in Response Body, result was " + info.success
  );
});

Write synthetic API tests (legacy runtime - Node.js 10 and lower)

Important

Tip

Use API http-request module

Important

Configure request options

Tip

Using optional metadata

Using a SSL option or agentOptions

Send a GET request

Send a POST request

NerdGraph example

Event API POST example

Validate results

Important

Event API validation example

Write synthetic API tests (legacy runtime - Node.js 10 and lower)

Important

Tip

Use API http-request module .css-21sua1{background:none;border:none;width:0;padding:0;}

Important

Configure request options

Tip

Using a SSL option or agentOptions

Send a GET request

Send a POST request

NerdGraph example

Event API POST example

Validate results

Important

Event API validation example

Use API http-request module