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:

  1. Names are routes, routes are names. GET /users/1234 handled by app.get('/users/:userId') is named after /users/:userId.
  2. Routes stack. Each entered middleware pushes its mount path on a name stack and pops it when it calls next(). A router mounted at /users with an endpoint at /:userId produces /users/:userId.
  3. 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.
  4. 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.
  5. 404s get special names. If nothing responds and the status is 404, the transaction is named <method> (not found), for example post (not found).
  6. 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

See newrelic-naming-rules.

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, or startWebTransaction URLs).
  • 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.

See Also