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
- Configuration and the Configuration Reference.
- API Overview.
- Distributed Tracing to follow requests across services.