Transaction Naming
Transaction names group requests in the APM UI: every request with the same name shares the same metrics, traces, and Apdex. Good names are specific enough to be useful but stable enough not to explode into thousands of variants (a metric grouping issue). This page explains how the agent names transactions, how to override names, and how naming rules work.
How Names Are Chosen
For Express and similar middleware-based frameworks, the agent names a transaction after the route that handled the request, not after the handler function (middleware is often anonymous). The repository's naming philosophy document summarizes it as six rules:
- Names are routes, routes are names.
GET /users/1234handled byapp.get('/users/:userId')is named after/users/:userId. - Routes stack. Each entered middleware pushes its mount path on a name stack and pops it when it calls
next(). A router mounted at/userswith an endpoint at/:userIdproduces/users/:userId. - The middleware that responds names the transaction. When a middleware sends the response (for Express,
res.send()), the name stack is frozen, so unwinding middleware does not change it. - Errors don't reset naming. If a middleware passes an error to
next(err), its path is kept on the stack, so the transaction is named after the failing route rather than the error handler. - 404s get special names. If nothing responds and the status is 404, the transaction is named
<method> (not found), for examplepost (not found). - Everything else gets the URI. If the name stack is empty and the status is not 404 (usually an uninstrumented feature), the URL is passed through naming rules and reported under
NormalizedUri.
The backstop
Rule 6 is dangerous for cardinality. The enforce_backstop setting (default true) makes any transaction not named by the API, rules, or metric normalization rules use NormalizedUri/*. Setting it to false reports them as Uri/<path> instead — only do this if you are sure your URLs have few distinct values.
Overriding Names in Code
| Method | Resulting name |
|---|---|
setTransactionName('checkout') |
Custom/checkout |
setControllerName('cart', 'add') |
Controller/cart/add |
startWebTransaction('/ws/msg', fn) |
Named from the URL you pass (rules still apply). |
startBackgroundTransaction('sync', 'Jobs', fn) |
Jobs/sync |
API names take precedence over naming rules, including rules sent from New Relic's servers.
Naming Rules
Naming rules rewrite the URL of a transaction before it is used as a name. Configure them in rules.name:
exports.config = {
rules: {
name: [
{ pattern: '^/api/v[0-9]+/users/[0-9]+$', name: '/api/users/:id' },
{ pattern: /^\/static\/.*/, name: '/static/*' },
{ pattern: '^/(en|fr|de)/products', name: '/$1/products' }
]
}
}
| Rule key | Required | Description |
|---|---|---|
pattern |
yes | A JavaScript regular expression, as a string or RegExp. Capture groups can be referenced in name. |
name |
yes | The replacement, with $1-style references. |
precedence |
no | Evaluation order; lower runs first. Default 500. |
terminate_chain |
no | Stop evaluating further rules after this one matches. Default true. |
replace_all |
no | Replace every match in the URL instead of the first. |
The schema description says additional attributes are ignored, but the code does read precedence, terminate_chain, and replace_all from each rule. A rule missing pattern or name logs Simple naming rules require a pattern. / ... require a replacement name. and is skipped.
From the environment, NEW_RELIC_NAMING_RULES takes a comma-separated list of JSON objects (the value is wrapped in [ ] and parsed):
export NEW_RELIC_NAMING_RULES='{"pattern":"^/u/[0-9]+","name":"/u/:id"},{"pattern":"^/static/","name":"/static"}'
At runtime, newrelic.addNamingRule(pattern, name) adds a rule at the head of the list with the highest precedence, terminating the chain. Note that addNamingRule prepends a / to name for you, while rules.name uses name exactly as written.
The reverse_naming_rules feature flag changes how rules with equal precedence are ordered.
Test rules before deploying
Use the bundled tool to see what your rules do to real URLs:
npx newrelic-naming-rules ./urls.txt
npx newrelic-naming-rules ./extra-rules.json ./urls.txt
Ignoring Transactions
Ignore rules drop matching transactions entirely (no metrics, traces, or events). Configure them with rules.ignore or add them with addIgnoringRule:
exports.config = {
rules: {
ignore: ['^/socket.io/.*/xhr-polling/', '^/healthz$']
}
}
The default list contains ^/socket.io/.*/xhr-polling/. Because arrays replace defaults, include it again if you set your own list and still use socket.io long-polling. NEW_RELIC_IGNORING_RULES takes a comma-separated list of patterns.
To ignore a single request dynamically, call newrelic.getTransaction().ignore().
URL Obfuscation
url_obfuscation rewrites URL paths before they are recorded, which helps when paths contain tokens or personal data. The code builds new RegExp(pattern, flags) and calls path.replace(regex, replacement) on the path of inbound transaction URLs (OpenTelemetry bridge) and of outbound HTTP/HTTP2 external calls. Query strings are not part of the path it receives.
exports.config = {
url_obfuscation: {
enabled: true,
regex: {
pattern: '/users/[^/]+',
flags: 'g',
replacement: '/users/**'
}
}
}
An invalid pattern logs Invalid regular expression for url_obfuscation.regex.pattern and leaves the path unchanged.
Avoiding Metric Grouping Issues
- Never put IDs, hashes, timestamps, or emails in names (from rules,
setTransactionName, orstartWebTransactionURLs). - Prefer route patterns (
/users/:id) over concrete paths. - Watch for transactions named
NormalizedUri/*: they indicate requests the framework instrumentation could not name — often an unsupported router.