Attributes, Privacy, and Security

Attributes are the key-value pairs attached to transactions, spans, errors, and browser data — request headers, request parameters, enduser.id, and your custom attributes. This page explains which attributes go where, how include and exclude rules are evaluated, and the settings that keep sensitive data out of New Relic: header capture, high security mode, message stripping, SQL obfuscation, and the security agent.

Destinations

Every attribute targets one or more destinations, and each destination has its own rule set:

Destination Settings prefix Attributes enabled by default
Transaction events transaction_events.attributes yes
Transaction traces transaction_tracer.attributes yes
Error events and traces error_collector.attributes yes
Browser monitoring browser_monitoring.attributes no
Span events span_events.attributes yes
Transaction segments transaction_segments.attributes yes

Each prefix has enabled, include, and exclude. The global attributes.enabled, attributes.include, and attributes.exclude apply to all destinations. attributes.enabled: false turns attribute capture off everywhere.

How Include and Exclude Rules Work

Rules are attribute-name patterns. A rule ending in * is a wildcard (prefix match); any other rule is an exact match.

exports.config = {
  attributes: {
    exclude: ['request.headers.*'],
    include: ['request.headers.userAgent']
  }
}

For each attribute and destination, AttributeFilter evaluates in this order:

  1. An exact global exclude → excluded.
  2. An exact destination exclude → excluded.
  3. An exact global include → included.
  4. An exact destination include → included.
  5. If no rule matches at all → the attribute keeps the destinations it was added with. (Destinations whose attributes.enabled is false are removed before any rule is checked.)
  6. Otherwise wildcard matches are compared by strength (the longer the matched prefix, the stronger): the attribute is included if a destination include is stronger than the destination exclude and at least as strong as the global exclude, or if a global include is stronger than both excludes.

In the example above, request.headers.userAgent is included (exact include), while every other request header is excluded.

Note: Header attribute names are camelCased versions of the HTTP header: request.headers.userAgent, request.headers.setCookie, response.headers.contentType. The schema notes that header rules must use camelCase to match.

attributes.include_enabled (default true) allows include patterns at all. attributes.filter_cache_limit (default 1000) caps how many rule results are cached.

Rules cannot be changed by server-side configuration; they are always local.

Request Headers and Parameters

Setting Default Effect
allow_all_headers false When true, all request headers are captured, minus those excluded. When false, only accept, content-length, content-type, referer, user-agent, and host are collected.
attributes.exclude [] The template newrelic.js ships with a list excluding cookies, authorization, proxyAuthorization, setCookie*, and x* request and response headers.

The template's combination (allow_all_headers: true plus that exclude list) captures most headers while dropping common secrets. If you remove the exclude list but keep allow_all_headers: true, cookies and authorization headers will be captured.

Request parameters (route and query parameters) are recorded as request.parameters.<name>.

Value Size

attributes.value_size_limit (default 256, maximum 4096) sets the maximum length of string values; longer values are truncated. Custom attribute keys longer than 255 bytes are rejected. See Attribute Limits.

Error Messages

strip_exception_messages.enabled: true redacts error messages: the first line of the stack becomes <ErrorName>: <redacted>. Use it when exception messages may contain user data.

SQL

transaction_tracer.record_sql controls query text in traces and slow query samples:

Value Effect
obfuscated (default) Literals replaced by ?.
raw Queries recorded as executed. Avoid unless queries never contain sensitive values.
off No query text; no slow query samples.

Slow query samples additionally need slow_sql.enabled: true (default false), and only queries slower than transaction_tracer.explain_threshold (default 500 ms) qualify. You can apply the same obfuscation yourself with newrelic.obfuscateSql().

datastore_tracer.instance_reporting.enabled and datastore_tracer.database_name_reporting.enabled (both true) control whether host/port and database names are reported.

High Security Mode

high_security: true (NEW_RELIC_HIGH_SECURITY=true) locks the agent into a conservative configuration. It must also be enabled for your account on the server; if the local and server values differ, the agent logs a message and acts as if disabled.

When enabled, the agent:

  • forces ssl: true, strip_exception_messages.enabled: true, allow_all_headers: false, transaction_tracer.record_sql: 'obfuscated', slow_sql.enabled: false, application_logging.forwarding.enabled: false, ai_monitoring.enabled: false, and profiling.enabled: false;
  • empties every attributes.include list (global and per destination);
  • adds request.parameters.* to attributes.exclude;
  • makes addCustomAttribute, addCustomSpanAttribute, and recordCustomEvent return false without recording;
  • drops custom attributes passed to noticeError and sends an empty error.message in error events.

Each forced change is logged as High Security Mode: <key> was set to <value>, coercing to <forced>.

Disabling Specific APIs

If you need to guarantee that code cannot send custom data, use the API kill switches: api.custom_attributes_enabled, api.custom_events_enabled, and api.notice_error_enabled (environment variables NEW_RELIC_API_CUSTOM_ATTRIBUTES, NEW_RELIC_API_CUSTOM_EVENTS, NEW_RELIC_API_NOTICE_ERROR).

Data Sent to New Relic About the Agent

The agent sends its configuration to New Relic when it connects. Before sending, it blanks proxy_pass, proxy_user, proxy, and certificates, and removes domain. The license key is part of the connection itself. Logs at trace level, and the audit_log feature, record outbound payloads locally; protect those log files.

Transport Security

The agent always connects with TLS: ssl cannot be disabled. For proxies, use proxy (a URL such as http://user:pass@host:port/, which overrides the other proxy settings) or proxy_host, proxy_port, proxy_user, proxy_pass. Add custom CA certificates (for TLS-intercepting proxies) to certificates:

const fs = require('node:fs')
exports.config = {
  proxy: process.env.HTTPS_PROXY,
  certificates: [fs.readFileSync('/etc/ssl/corp-ca.crt', 'utf8')]
}

The Security Agent

The package depends on @newrelic/security-agent (New Relic's IAST/RASP security agent, under the New Relic Software License). It only starts when security.agent.enabled is true. Its behavior is configured through the security.* settings (mode IAST or RASP, validator URL, detection toggles, scan schedule, exclusions) — see the security settings.

See Also