Upgrade scripted API monitors to Node.js 22

We're introducing our latest scripted API monitor runtime, featuring the Latest Node.js version (currently Node.js 22). The Latest runtime automatically uses the most current Node.js release that New Relic supports, ensuring your API monitors run in an environment that matches modern Node.js standards, providing enhanced security, stability, and performance.

Action required: Node.js 22 upgrade impact

As part of the upgrade from Node.js 16 to Node.js 22, the runtime is stricter about process lifecycles. If your monitor scripts contain unhandled open handles (such as unresolved promises, lingering timers, or unclosed network connections), your monitors will fail.

To resolve this: Validate your monitor scripts against the Latest runtime to ensure all handles are properly closed before the script finishes executing. Failed validations appear in the Runtime Upgrades UI. See Troubleshoot runtime upgrade errors.

Who is affected

New Relic automatically handles the upgrade process for:

• Scripted API monitors on public locations
• Scripted API monitors on both public and private locations (hybrid)

New Relic applies automated validation and upgrade to all location configurations.

What is Latest?

The Latest runtime option in the monitor create/upgrade dropdown automatically uses the most recent Node.js version that New Relic supports. Instead of pinning to a specific Node.js version (like Node.js 16 or Node.js 20), Latest ensures your monitors always run on the newest available Node.js release with the latest features, performance improvements, and security updates.

Upgrade monitors via NerdGraph

To upgrade your monitor runtimes programmatically, use the NerdGraph mutation below. You need your monitor's entity GUID (available in the monitor settings).

Scripted API monitors

mutation {
  syntheticsUpdateScriptApiMonitor(
    guid: "YOUR_MONITOR_GUID"
    monitor: {
      runtime: { runtimeType: "NODE_API", runtimeTypeVersion: "LATEST" }
    }
  ) {
    errors {
      description
      type
    }
  }
}

The automated upgrade process

To ensure a smooth transition to the latest Node.js runtime, New Relic proactively tests your existing monitors. The process includes:

Troubleshooting upgrade issues

The most common issue when upgrading to Node.js 22 is unhandled open handles, including unresolved promises, lingering timers, unclosed connections, and HTTP/HTTPS connections. For detailed solutions and code examples for each issue type, see Troubleshoot runtime upgrade errors.

Node.js 22 breaking changes

In addition to stricter open handle management, Node.js 22 includes other changes you should be aware of:

Updated module support

• ES modules: Better support for ES modules, but ensure your imports are properly configured
• CommonJS: CommonJS modules still work but may have stricter validation

Deprecated APIs

Some APIs deprecated in earlier Node.js versions have been removed in Node.js 22. Check the Node.js 22 changelog for details on removed features.

Performance improvements

Node.js 22 includes performance improvements that may affect timing-sensitive tests. Consider reviewing timeouts if your monitors rely on specific timing behavior.

Best practices for Node.js 22

To ensure your scripted API monitors work smoothly with Node.js 22:

1. Use async/await: Convert callback-based code to async/await for better error handling.
2. Clean up resources: Always close connections, clear timers, and remove event listeners.
3. Handle all promises: Never create a promise without awaiting it or handling its result.
4. Set appropriate timeouts: Use reasonable timeouts for API calls to prevent hanging.
5. Test locally: Test your scripts with Node.js 22 locally before upgrading production monitors.

Example: Complete API monitor

const assert = require('assert');
const $http = require('request');
const { promisify } = require('util');

// Promisify request methods
const httpGet = promisify($http.get);
const httpPost = promisify($http.post);

async function runAPITest() {
  try {
    // 1. Test GET endpoint
    console.log('Testing GET endpoint...');
    const getResponse = await httpGet('https://api.example.com/users');
    assert.equal(getResponse.statusCode, 200, 'GET request failed');

    // 2. Parse and validate response
    const users = JSON.parse(getResponse.body);
    assert(Array.isArray(users), 'Response is not an array');
    assert(users.length > 0, 'No users returned');

    // 3. Test POST endpoint
    console.log('Testing POST endpoint...');
    const postResponse = await httpPost({
      url: 'https://api.example.com/users',
      json: true,
      body: {
        name: 'Test User',
        email: 'test@example.com'
      }
    });
    assert.equal(postResponse.statusCode, 201, 'POST request failed');

    console.log('All tests passed!');
  } catch (error) {
    console.error('Test failed:', error.message);
    throw error; // Fail the monitor
  }
}

// Run the test
await runAPITest();

Frequently asked questions

What monitor types are affected? Scripted API monitors. Scripted browser monitors are affected separately — see Upgrade synthetic monitors to the latest Chrome and Node.js 22. Simple browser and ping monitors are not affected.

Can I test my scripts locally before upgrading? Yes. Install Node.js 22 locally and test your monitor scripts to identify issues before the upgrade.

Can I rollback if my monitor fails after upgrade? Yes. You can change the runtime version back in the monitor settings or via NerdGraph.

When will my monitors be automatically upgraded? New Relic performs validation first. If validation succeeds, New Relic automatically upgrades monitors. If validation fails, you see the failure in the Runtime Upgrades UI and must manually fix and upgrade.

Need help?

If you encounter issues during the upgrade process:

1. Check the Runtime Upgrades UI in your Synthetics Nerdlet for specific error messages.
2. Review your monitor scripts for unhandled promises and open connections.
3. Test your scripts locally with Node.js 22 before upgrading.
4. Contact New Relic Support for assistance troubleshooting validation failures.

Related documentation:

• Write synthetic API tests
• Import Node.js modules
• Scripted monitor runtime environment
• Runtime upgrade UI
• Troubleshoot runtime upgrade errors