---
title: Node.js agent transaction tracer settings
source: https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration-transaction-tracer-settings
---

This page covers the Node.js agent settings for transaction tracing, including trace thresholds, SQL recording modes, slow query collection, and datastore instance reporting.

> #### 💡 TIP
>
> Back to the full settings index: [Node.js agent configuration](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/installation-configuration/nodejs-agent-configuration)

## Transaction tracer variables [#tx_tracer_config]

The agent groups your requests into [transactions](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#transaction), which are used to:

-   Visualize where your app spends its time (in transaction breakdowns).
-   Identify slow requests.
-   Group metrics.
-   Isolate other issues, such as slow [database performance](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/databases-slow-queries-dashboard).

This section defines the Node.js agent variables in the order they typically appear in the `transaction_tracer: {` section of your app's `newrelic.js` configuration file.

> #### ⚠️ IMPORTANT
>
> Do not use brackets `[suffix]` at the end of your transaction name. New Relic automatically strips brackets from the name. Instead, use parentheses `(suffix)` or other symbols if needed.

**enabled**

| Type                              | Boolean                       |
| --------------------------------- | ----------------------------- |
| Default                           | `true`                        |
| [Environ variable](#environment)  | `NEW_RELIC_TRACER_ENABLED`    |
| [Server-side label](#server-side) | `Enable transaction tracing?` |

When enabled, the agent collects slow [transaction traces](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/transaction-traces).

**explain_threshold**

| Type                             | Integer                       |
| -------------------------------- | ----------------------------- |
| Default                          | `500`                         |
| [Environ variable](#environment) | `NEW_RELIC_EXPLAIN_THRESHOLD` |

Minimum query duration (in milliseconds) for a transaction to be eligible for [slow queries](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/viewing-slow-query-details) in [transaction traces](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/transaction-traces).

**record_sql**

| Type                             | String (`obfuscated`, `off`, or `raw`) |
| -------------------------------- | -------------------------------------- |
| Default                          | `obfuscated`                           |
| [Environ variable](#environment) | `NEW_RELIC_RECORD_SQL`                 |

This option affects both [slow queries](#slow-queries) and `record_sql` for transaction traces. It can have these values: `off`, `obfuscated`, or `raw`.

When set to `off` no slow queries will be captured, and backtraces and SQL will not be included in transaction traces. If set to `raw` or `obfuscated`, the agent sends raw or obfuscated SQL and a slow query sample to the [collector](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#collector). The agent may also send SQL when other criteria are met, such as when `slow_sql.enabled` is set.

**top_n**

| Type                             | Integer                  |
| -------------------------------- | ------------------------ |
| Default                          | `20`                     |
| [Environ variable](#environment) | `NEW_RELIC_TRACER_TOP_N` |

Defines the maximum number of requests eligible for [transaction traces](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/transaction-traces).

Transactions are named based on the request, and `top_n` refers to the "top n slowest transactions" grouped by these names. The module replaces a recorded trace with a new trace only if the new trace is slower than the previous slowest trace of that name. The default value for this setting is `top_n: 20`, because the [**Transactions** page](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/transaction-traces) also defaults to the 20 slowest transactions.

The Node.js agent captures at least five different slow transactions in the first harvest cycle after start up. It will also reset and capture different transactions if no slow transactions have been captured for the last five [harvest cycles](https://docs.newrelic.com/docs/apm/new-relic-apm/getting-started/glossary#harvest-cycle). This allows you to see more information about more of your app's request paths, at the possible cost of not focusing on the absolutely slowest request for that harvest cycle.

> #### 💡 TIP
>
> To record the absolute slowest transaction over the last minute, you can set `top_n: 0` or `top_n: 1`. However, this causes one very slow route to dominate your transaction traces.

**transaction_threshold**

| Type                              | Integer or `apdex_f`         |
| --------------------------------- | ---------------------------- |
| Default                           | `apdex_f`                    |
| [Environ variable](#environment)  | `NEW_RELIC_TRACER_THRESHOLD` |
| [Server-side label](#server-side) | `Threshold`                  |

Sets the time, in seconds, for a [transaction trace](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/transaction-traces) to be considered slow. The default value is `apdex_f`; this sets the trace threshold to four times your application's [Apdex T](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#apdex_t). If a number is provided, it is set in seconds.

The default `apdex_t` is 500 milliseconds. If your transaction threshold is set to `apdex_f`, a "slow" transaction is 2 seconds.

**attributes.enabled**

| Type                             | Boolean                                           |
| -------------------------------- | ------------------------------------------------- |
| Default                          | `true`                                            |
| [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_ENABLED` |

If `true`, the agent captures attributes from transaction traces.

> #### ⚠️ CAUTION
>
> Any header-related include/exclude rules must be in camelCase form to be filtered.

**attributes.exclude**

| Type                             | Array                                             |
| -------------------------------- | ------------------------------------------------- |
| Default                          | `[]`                                              |
| [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_EXCLUDE` |

Prefix of attributes to exclude from transaction traces. Allows `*` as wildcard at end.

**attributes.include**

| Type                             | Array                                             |
| -------------------------------- | ------------------------------------------------- |
| Default                          | `[]`                                              |
| [Environ variable](#environment) | `NEW_RELIC_TRANSACTION_TRACER_ATTRIBUTES_INCLUDE` |

Prefix of attributes to include in transaction traces. Allows `*` as wildcard at end.

## Slow queries variables [#slow-queries]

This section defines the Node.js agent variables in the order they typically appear in the `slow_sql: {` section of your app's `newrelic.js` configuration file. These options control behavior for slow queries, but do not affect SQL nodes in transaction traces.

**enabled**

| Type                             | Boolean                      |
| -------------------------------- | ---------------------------- |
| Default                          | `false`                      |
| [Environ variable](#environment) | `NEW_RELIC_SLOW_SQL_ENABLED` |

When enabled, the agent collects [slow query details](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/viewing-slow-query-details).

**max_samples**

| Type                             | Integer                     |
| -------------------------------- | --------------------------- |
| Default                          | `10`                        |
| [Environ variable](#environment) | `NEW_RELIC_MAX_SQL_SAMPLES` |

Defines the maximum number of slow queries the agent collects per minute. The agent discards additional queries after the limit is reached.

> #### ⚠️ IMPORTANT
>
> Increasing this limit increases memory usage.

## Datastore tracer variables [#datastore-tracer]

This section defines the Node.js agent variables in the order they typically appear in the `datastore_tracer` section of your app's `newrelic.js` configuration file. These options control behavior for collecting datastore instance metrics.

**instance_reporting.enabled**

| Type                             | Boolean                                          |
| -------------------------------- | ------------------------------------------------ |
| Default                          | `true`                                           |
| [Environ variable](#environment) | `NEW_RELIC_DATASTORE_INSTANCE_REPORTING_ENABLED` |

When enabled, the agent collects datastore instance metrics (such as host and port) for [some database drivers](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-instance-level-database-information). These are reported on slow query traces and transaction traces.

**database_name_reporting.enabled**

| Type                             | Boolean                                               |
| -------------------------------- | ----------------------------------------------------- |
| Default                          | `true`                                                |
| [Environ variable](#environment) | `NEW_RELIC_DATASTORE_DATABASE_NAME_REPORTING_ENABLED` |

When enabled, the agent collects database name on slow query traces and transaction traces for [some database drivers](https://docs.newrelic.com/docs/agents/nodejs-agent/supported-features/nodejs-instance-level-database-information).