Quick Start

This tutorial takes a small Express application from zero to reporting data to New Relic, then adds a custom attribute, a custom event, and a background transaction. It assumes Node.js 22.16.0 or newer and a New Relic license key.

1. Create a project

mkdir nr-demo && cd nr-demo
npm init -y
npm install express newrelic

2. Write a small server

Create server.js:

'use strict'
const newrelic = require('newrelic')
const express = require('express')

const app = express()

app.get('/hello/:name', (req, res) => {
  // Attach searchable data to the current transaction and span.
  newrelic.addCustomAttribute('greetedName', req.params.name)
  res.send(`Hello, ${req.params.name}!`)
})

app.get('/order', (req, res) => {
  // Record a custom event, queryable with NRQL as `SELECT * FROM OrderPlaced`.
  newrelic.recordCustomEvent('OrderPlaced', { total: 42.5, items: 3 })
  res.send('ordered')
})

app.listen(3000, () => console.log('listening on :3000'))

Requiring newrelic here only gives you the API object; the agent itself will be preloaded with -r in step 4. Because the agent caches itself on first load, the second require('newrelic') returns the same instance.

3. Configure the agent

Use environment variables for this tutorial:

export NEW_RELIC_APP_NAME="nr-demo"
export NEW_RELIC_LICENSE_KEY="your-license-key"
export NEW_RELIC_NO_CONFIG_FILE=true
export NEW_RELIC_LOG=stdout

NEW_RELIC_LOG=stdout sends the agent log (logging.filepath) to the console instead of newrelic_agent.log, which makes the next step easier to follow.

4. Start with the agent preloaded

node -r newrelic server.js

Among the output you should see JSON log lines whose messages include:

Using New Relic for Node.js. Agent version: 14.13.0; Node version: v22.16.0.
NEW_RELIC_NO_CONFIG_FILE set, deferring to environment variables.
listening on :3000

At the default info level the log is terse. Set NEW_RELIC_LOG_LEVEL=debug to also see New Relic for Node.js is connected to New Relic. once the connection succeeds.

5. Generate traffic

curl http://localhost:3000/hello/ada
curl http://localhost:3000/order

Within a few minutes the application nr-demo appears in New Relic APM. The first request is reported as a transaction named after the Express route /hello/:name and the GET method, not after the concrete URL /hello/ada (see Transaction Naming), carrying the greetedName attribute.

6. Add a background transaction

Work that does not start from an inbound request (a timer, a queue consumer, a cron job) is not tracked unless you wrap it. Add to server.js:

setInterval(() => {
  newrelic.startBackgroundTransaction('cleanup', 'Jobs', async () => {
    // The transaction ends when this promise settles.
    await new Promise((resolve) => setTimeout(resolve, 50))
  })
}, 10_000)

This produces a non-web transaction named Jobs/cleanup. See Transactions and Segments for the rules about when such a transaction ends.

7. Move to a configuration file (optional)

For long-lived hosts, a file is often easier to manage. Copy the template and validate it:

cp ./node_modules/newrelic/newrelic.js ./newrelic.js
npx newrelic validate-config -c ./newrelic.js

Remember to unset NEW_RELIC_NO_CONFIG_FILE; while it is true, the file is never read. Environment variables still override values in the file.

8. Shut down cleanly in scripts

Short-lived scripts can exit before the agent's next harvest. Flush data before exiting:

newrelic.shutdown({ collectPendingData: true, timeout: 5000 }, (err) => {
  process.exit(err ? 1 : 0)
})

See shutdown for the exact semantics.

What You Have Now

  • An Express app instrumented automatically (routes, timing, errors).
  • A custom attribute and a custom event.
  • A background transaction for timer-driven work.

Next Steps