---
title: Java agent transaction tracer settings
source: https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-transaction-tracer-settings
---

Transaction tracer settings control how the agent captures detailed information about slow transactions, transaction events, and message tracing.

> #### 💡 TIP
>
> Back to the full settings index: [Java agent configuration](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file)

## Transaction tracer

Set the transaction tracer options in the `transaction_tracer` section. These options can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.transaction_tracer` prefixed system property.

[Transaction tracing](https://docs.newrelic.com/docs/traces/transaction-traces) captures deep information about slow transactions and sends this to the New Relic service. The transaction includes the exact call sequence of the transactions, including any query statements issued.

> #### ⚠️ 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`  |

The transaction tracer is enabled by default. Set this to `false` to turn it off.

**explain_enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Determines whether the agent will capture the `EXPLAIN` plan for slow queries. [Only supported for MySQL and PostgreSQL.](https://docs.newrelic.com/docs/agents/java-agent/getting-started/compatibility-requirements-java-agent#JDBC)

**explain_threshold**

| Type    | Float |
| ------- | ----- |
| Default | `0.5` |

Threshold in seconds for query execution time below which the slow query and the `EXPLAIN` plan ([if supported](https://docs.newrelic.com/docs/agents/java-agent/getting-started/compatibility-requirements-java-agent#JDBC)) will not be captured. Relevant to slow queries only when `record_sql` is set to `raw` or `obfuscated`. Relevant to `EXPLAIN` plans only when `explain_enabled` is set to `true`.

**exec_call_sql_regex_disabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `false` |

For large SQL statements, executing the regular expressions that attempt to parse exec and call statements can take a significant amount of time.
Setting this to true will disable the execution of these complex regular expressions.

This config exists in Java agent version 8.25.0+.

**insert_sql_max_length**

| Type    | Integer |
| ------- | ------- |
| Default | `2000`  |

The character limit for the SQL query string. If you have many slow SQL queries with large chunks of information, this could negatively affect performance or how quickly you see your data in New Relic. Increase the value gradually until you find the right balance of information and performance.

**log_sql**

| Type    | Boolean |
| ------- | ------- |
| Default | `false` |

Set to `true` to enable logging of queries to the agent log file instead of uploading to New Relic. Queries are logged using the `record_sql` mode.

**record_sql**

| Type    | String       |
| ------- | ------------ |
| Default | `obfuscated` |

When the transaction tracer is on, query statements can optionally be recorded. The recorder has three modes:

-   `off`: Send no queries.
-   `raw`: Send the query statement in its original form.
-   `obfuscated`: Strips out numeric and string literals.

**sql_metadata_comments**

| Type    | String   |
| ------- | -------- |
| Default | `(none)` |

Controls the addition of comments to the beginning of executed SQL statements to be used by the New Relic Query Performance Monitoring
product for entity linking. Default is false.

A resulting comment would resemble this:
/_nr_service_guid=MTE3NDc2MDB8QVBNfAAAAAxJQEEEEE9OfDI4MTc5NDEIEA_/

**stack_based_naming (Play 2.x+ only)**

| Type    | Boolean                                                                                      |
| ------- | -------------------------------------------------------------------------------------------- |
| Default | `false` Defaulted to `true` until Java agent version 3.12.1, when it was changed to `false`. |

This option is for Play 2.x+ only. Play/Scala instrumentation can use `Thread.getStackTrace()` to improve tracer naming, but at the cost of increased overhead.

**stack_trace_threshold**

| Type    | Integer |
| ------- | ------- |
| Default | `0.5`   |

Defines a threshold (in seconds) for collecting stack traces from an SQL call. When SQL statements exceed this threshold, the agent will capture the current stack trace. This is useful for pinpointing where long SQL calls originate from.

**top_n**

| Type    | Integer |
| ------- | ------- |
| Default | `20`    |

Use this setting to control the variety of your transaction traces. `top_n` is an integer that represents the number of unique, slow transactions that traces will be created for.

-   If you want transaction traces to more accurately reflect the actual slowest transactions in your app, make this value **lower**.
-   If you want to sample a more diverse array of transactions, make the value **higher**.

    A value of `0` would mean that **only** the slowest transaction is always traced. This is considered not to be optimal, though, because you may have one or two transactions that are always the slowest, and repeatedly seeing those same transaction traces will probably not give you much value.

    If the same transaction is often the slowest, the `top_n` setting allows the Java agent (over time) to sample the slowest `n` transactions. This gives you greater variety and more insight into your application.

**transaction_threshold**

| Type    | String (float) |
| ------- | -------------- |
| Default | `apdex_f`      |

The time threshold used to determine when a transaction is eligible to be traced. When the transaction's response time exceeds this threshold, the transaction becomes eligible for a [transaction trace](https://docs.newrelic.com/docs/apm/transactions/transaction-traces/transaction-traces). If sampled, that transaction trace will be recorded and sent to New Relic.

The default is `apdex_f` (default), which sets the threshold to be the ["Frustrated"](https://docs.newrelic.com/docs/accounts-partnerships/education/getting-started-new-relic/glossary#apdex_f) [Apdex](https://docs.newrelic.com/docs/site/apdex-measuring-user-satisfaction) level (four times the `apdex_t` value). You can also set a specific time threshold by entering a float value that represents a number of seconds.

**slow_query_whitelist (DEPRECATED)**

| Type    | String |
| ------- | ------ |
| Default | (none) |

> #### ⚠️ IMPORTANT
>
> This config has been deprecated as of agent version 5.10.0 and will be removed in a future agent version. Instead use `collect_slow_queries_from`.

By default, [high-security mode](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security) does not allow the agent to collect [slow queries](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/viewing-slow-query-details). Enable this option to collect Cassandra queries from the DataStax driver, even with high security enabled. If you don't use high security, the agent collects slow queries automatically.

For DataStax driver 2.1.2, add this rule to your allow list:

````yml
transaction_tracer:
  slow_query_whitelist:
    'com.newrelic.instrumentation.cassandra-datastax-2.1.2'
```

For DataStax driver 3.0.0, add this rule to your allow list:

```yml
transaction_tracer:
  slow_query_whitelist:
    'com.newrelic.instrumentation.cassandra-datastax-3.0.0'
```

````

**collect_slow_queries_from**

| Type    | String |
| ------- | ------ |
| Default | (none) |

By default, [high-security mode](https://docs.newrelic.com/docs/accounts-partnerships/accounts/security/high-security) does not allow the agent to collect [slow queries](https://docs.newrelic.com/docs/apm/applications-menu/monitoring/viewing-slow-query-details). Enable this option to collect Cassandra queries from the DataStax driver, even with high security enabled. If you don't use high security, the agent collects slow queries automatically.

For DataStax driver 2.1.2, add this rule to your allow list:

````yml
transaction_tracer:
  collect_slow_queries_from:
    'com.newrelic.instrumentation.cassandra-datastax-2.1.2'
```

For DataStax driver 3.0.0, add this rule to your allow list:

```yml
transaction_tracer:
  collect_slow_queries_from:
    'com.newrelic.instrumentation.cassandra-datastax-3.0.0'
```

````

**attributes.enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

This setting can be used to turn on or off all attributes for transaction traces. If `attributes.enabled` at the root level is `false`, no attributes will be sent to transaction traces regardless on how this property (`transaction_tracer.attributes.enabled`) is set.

**attributes.include**

| Type    | List of strings |
| ------- | --------------- |
| Default | (none)          |

If attributes are enabled for transaction traces, all attribute keys found in this list will be sent to New Relic in transaction traces. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes).

**attributes.exclude**

| Type    | List of Strings |
| ------- | --------------- |
| Default | (none)          |

All attribute keys found in this list will not be sent to New Relic in transaction traces. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes).

**token_limit**

| Type    | Integer |
| ------- | ------- |
| Default | `3000`  |

Limits the number of Tokens that can be created per Transaction. Increasing this value may impact performance, because it increases the amount of memory the agent uses and the amount of data sent to New Relic.

**segment_limit**

| Type    | Integer |
| ------- | ------- |
| Default | `3000`  |

Limits the number of segments that can be created per transaction. Increasing this value may impact performance, because it increases the amount of memory the agent uses and the amount of data sent to New Relic.

## Transaction events [#Transaction_Events]

Set the transaction events options in the `transaction_events` section. These options can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.transaction_events` prefixed system property.

Transaction events data is used to display histograms and percentiles in the UI.

> #### ⚠️ IMPORTANT
>
> Previously, this section was called `analytics_events`. If your configuration file still uses `analytics_events`, update your agent to use `transaction_events`.

**enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Enable the transaction events service.

**max_samples_stored**

| Type    | Integer |
| ------- | ------- |
| Default | `2000`  |
| Max     | `10000` |

The maximum number of sampled transaction events reported every 60 seconds.

> #### ⚠️ IMPORTANT
>
> The minimum number of sample transaction events is 12. Agents with version 5.5.0 or higher send data every 5 seconds. If you set the number of events to less than 12, the number of events sent during the harvest cycle will be insufficient, resulting in no data being sent.

**custom_request_headers**

| Type    | List of maps |
| ------- | ------------ |
| Default | (none)       |

> #### ⚠️ IMPORTANT
>
> Unlike other settings, `custom_request_headers` have to be paired together and must be set in the `newrelic.yml` file. They can't be overwritten by Java virtual machine arguments (system property) or environment variables.

A list of maps with the paired keys `header_name` and the optional `header_alias`. Choose one or more custom HTTP request headers to add as transaction attributes.

You can list multiple header configurations:

````yml
transaction_events:
  custom_request_headers:
    -
      header_name: "X-Custom-Header-1"
    -
      header_name: "X-Custom-Header-2"
      header_alias: "CustomHeader2alias"
```

In the first map set, `X-Custom-Header-1` is captured and reported by the agent as the header name for a corresponding value from the request object. The `header_name` will also be the name of the attribute sent to New Relic.

In the second map set, the request header is `X-Custom-Header-2`, but the `CustomHeader2alias` is the name sent to New Relic.

````

**attributes.enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

This setting can be used to turn on or off all attributes for transaction events. If `attributes.enabled` is `false` at the root level, then no attributes will be sent to transaction events regardless of how this property is set under `transaction_events`.

**attributes.include**

| Type    | List of Strings |
| ------- | --------------- |
| Default | (none)          |

If attributes are enabled for transaction events, all attribute keys found in this list will be sent to New Relic in transaction events. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes).

**attributes.exclude**

| Type    | List of Strings |
| ------- | --------------- |
| Default | (none)          |

All attribute keys found in this list will not be sent to New Relic in transaction events. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes).

## Transaction segments

Set the transaction segments options in the `transaction_segments` section. These options can be [overridden](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) with a `newrelic.config.transaction_segments` prefixed system property.

Transaction segments represent discrete pieces of work (generally method calls) and are displayed within [transaction traces](https://docs.newrelic.com/docs/traces/transaction-traces).

> #### ⚠️ IMPORTANT
>
> Transaction segment attribute filtering requires [Java agent version 4.10.0 or higher](https://docs.newrelic.com/docs/agents/java-agent/installation/upgrade-java-agent).

**attributes.enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

This setting can be used to turn on or off all attributes for transaction segments. If `attributes.enabled` at the root level is `false`, no attributes will be sent to transaction segments regardless on how this property (`transaction_segments.attributes.enabled`) is set.

**attributes.include**

| Type    | List of strings |
| ------- | --------------- |
| Default | (none)          |

If attributes are enabled for transaction segments, all attribute keys found in this list will be sent to New Relic in transaction segments. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes).

**attributes.exclude**

| Type    | List of Strings |
| ------- | --------------- |
| Default | (none)          |

All attribute keys found in this list will not be sent to New Relic in transaction segments. For more information, see the [agent attribute rules](https://docs.newrelic.com/docs/apm/other-features/attributes/agent-attributes).

## Message tracer [#Transaction_Tracer]

Set message tracer options in the `message_tracer` section. You can [override](https://docs.newrelic.com/docs/apm/agents/java-agent/configuration/java-agent-configuration-config-file#System_Properties) these settings with a `newrelic.config.message_tracer` prefixed system property.

**segment_parameters.enabled**

| Type    | Boolean |
| ------- | ------- |
| Default | `true`  |

Adds message properties to tracer attributes. Set this to `false` to turn it off.