Our PHP agent has a number of settings to fine-tune the types and amounts of data reported. For most users, the default values produce the best possible mix of overhead and utility. However, you can change the settings for your specific needs.
Important
Always restart your web server after changing INI settings. Otherwise, they may not take effect immediately.
Configuration order of precedence
Here is a simple illustration of the order of precedence that the PHP agent follows for configuration. Server-side configuration is not applicable. The only values you can change in the UI for apps using the PHP agent are the app's alias and its Apdex-T value.
With New Relic's PHP agent, API settings override per-directory configuration settings. Per-directory settings override the php.ini
file settings. Server-side configuration is not applicable.
Configuration file variables
During installation, the newrelic-install
script provides information about the configuration files it created or a list of files you need to edit. By default it will attempt to create a configuration file named newrelic.ini
.
In some cases, you may be instructed to add configuration options to your php.ini
file. Only do this if necessary. Exactly which file you need to edit depends on how your particular version (or versions) of PHP were configured.
The two most common configurations are:
- Use a single
newrelic.ini
file. This is usually the default if you have installed or compiled PHP yourself with no special options. - Scan a given directory for all
.ini
files.
If you are unsure which file to edit:
From the command line, review the output of
php -i
.In a browser, review the output of a page containing the script:
<?php phpinfo(); ?>If the
newrelic.ini
file appears, use it.
Variable scope
Each variable for your newrelic.ini
file has a defined scope. The scope controls where the setting can be established or modified.
The two scopes supported for New Relic settings are:
- SYSTEM: Values set globally in the global
newrelic.ini
file. - PERDIR: Values set on a per-directory basis.
Each can also be set at a more general level. Valid locations for each are:
Can be set for: | SYSTEM | PERDIR |
---|---|---|
Set in the global | ||
Set on a per-directory basis. |
Important
You cannot use ini_set()
for New Relic settings.
Variable type
Each variable for your newrelic.ini
file has a defined type. The type specifies the syntax for the value you use.
Variable type | Formatting and contents |
---|---|
String | String values can contain any alphanumeric character and punctuation. The value is delimited by quotes. |
Boolean | A logical true or false setting. Valid values are:
|
Number | Numeric values can only contain digits, plus a period to indicate floats. Unless otherwise stated, all numbers are integers, not floats. |
Duration | A string value delimited by quotes that represent a time duration. Use character flags to delimit time components. If there are no flags, the time is in milliseconds.
|
General configuration settings
These settings are available in the newrelic.ini
file.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
This config option sets the application name that data is reported under in APM. We highly recommends that you replace the default name with a descriptive name to avoid confusion and unintended aggregation of data. Data for all applications with the same name will be merged in New Relic, so set this carefully.
For all application-naming options, including per-directory settings, see Name your PHP application.
The setting's value is a semicolon-separated list of up to three application names. The first name in the list is the primary application name. It must be unique for each account. The application name is used as a key into a cache. When using multiple names for an app, New Relic only uses the first name for caching. Therefore, each application name can only appear as the first element once.
If you set newrelic.appname="App1;App2"
and later in the code set newrelic.appname="App1;App3"
, the second one will appear not to work. It will report to App1 and App2 because of the caching.
If you need overlapping application names, set the common application name in the second or third positions. For example: newrelic.appname="App2;App1"
and newrelic.appname="App3;App1"
. This is useful, for example, when you want to track a superset of applications.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Caution
This setting has been deprecated and may not behave as expected. Instead, use attribute properties.
To set this value programmatically, use the newrelic_capture_params()
API function.
If you pass sensitive information directly in the URL, keep this disabled.
If set to true
, this will enable the recording of parameters passed to a PHP script via the URL (everything after the ?
in the URL) in transaction traces. These will appear under the Parameters dropdown when displaying transaction traces.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: | (auto-detected) |
The New Relic PHP agent automatically detects the frameworks it supports, but problems may arise if you are using experimental new versions or if you have customized the framework. This setting disables automatic framework detection, instead telling the agent to attempt to name transactions according to the specified framework.
Specifying "no_framework"
will disable framework-related transaction naming entirely.
Use any of the following values, as appropriate:
"cakephp"
"codeigniter"
"drupal"
(for Drupal 6 and 7)"drupal8"
(for Drupal 8 and 9)"joomla"
"laravel"
"magento"
"magento2"
"mediawiki"
"slim"
"symfony2"
(for Symfony 3 - Symfony 2.x is not supported)"symfony4"
(for Symfony 4 and 5)"wordpress"
"yii"
"zend"
"zend2"
(for Zend Framework 2 and 3)"no_framework"
(to force no framework even if one was detected)If the framework auto-detection fails, this command will also fail.
Tip
Check the PHP compatibility page for the latest information on supported framworks.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
Caution
This setting has been deprecated and may not behave as expected. Instead, use attribute properties.
Use the newrelic.ignored_params
setting to specify a comma-separated list of parameter names to be excluded from the list of parameters sent to the New Relic servers. Enclose the string values with quote marks.
If you enable parameter capturing with newrelic.capture_params
, there may be parameters with sensitive user data you do not want to be captured by New Relic or visible in transaction traces. Use this to block the recording of this data.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
Notes: | Introduced in agent version 3.0. |
Sets the New Relic to use. In a multi-tenant system this can be set on a per-directory basis.
Tip
When you upgrade from an old agent version to 3.0 or higher, the license will be removed from your daemon configuration file (with a comment explaining why) and stored in the file /etc/newrelic/upgrade_please.key
. Copy the license out of that file and set it in your newrelic.ini
file. Delete the upgrade_please.key
file.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the level of detail of messages sent to the log file. Possible values, in increasing order of detail, include:
error
warning
info
verbose
debug
verbosedebug
When reporting any agent issues to New Relic technical support,
verbosedebug
is the most useful setting. However, this can generate a lot of information very quickly, so avoid keeping the agent atverbosedebug
level for longer than it takes to reproduce the problem you are experiencing.When reporting any agent issues to New Relic Technical Support, you may be asked to set this to a custom level, enabling debugging only for certain subsystems. Custom levels are beyond the scope of this document.
Scope: | PERDIR |
---|---|
Type: | Number |
Default: |
|
Notes: | This used to be |
Sets the level of detail in a transaction trace:
When set to
1
, all server calls are traced.When set to
0
, traces only include internally instrumented calls by New Relic and those defined by the user usingnewrelic.transaction_tracer.custom
.The default level of
1
does have a performance impact. If you need to improve performance, try setting the detail level to0
.When not tracing all server calls, blocks of time in transaction traces will be labeled as uninstrumented time, and only certain functions (defined internally by the agent) are instrumented. Even when reporting all calls, there may be uninstrumented time in the traces.
Scope: | SYSTEM |
---|---|
Type: | Boolean |
Default: |
|
Enables high security for all applications. When high security is set to true
, the following behaviors take effect:
Data will not be sent to New Relic unless the newrelic-daemon is using a secure connection (HTTPS). If the PHP process spawns a newrelic-daemon, it will be configured to use HTTPS regardless of the value of
newrelic.daemon.ssl
.Raw query strings will never be gathered, regardless of the value of
newrelic.transaction_tracer.record_sql
.Request attributes will never be captured, regardless of the
newrelic.attributes
configuration settings.The
newrelic_add_custom_parameter
andnewrelic_set_user_attributes
API function will have no effect, and they will returnfalse
.The
newrelic_record_custom_event
API function will not submit any events to New Relic.The agent strips exception messages from errors.
Caution
If you change the
newrelic.high_security
setting, you must also change the security setting in the APM user interface. If the two settings do not match, then no data will be collected. For more information, see High security.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
Adds tags.
Example tags
"Server:One;Data Center:Primary"
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the hostname to be displayed in the APM UI. If set, this overrides the default hostname that the agent captures automatically.
If you're using New Relic CodeStream to monitor performance from your IDE you may also want to associate repositories with your services and associate build SHAs or release tags with errors.
Daemon .ini settings
The values of these settings control the daemon startup. When the agent detects that the daemon needs to be started, it will convert these options into the appropriate command line options for the daemon.
All of these settings mirror the settings in the newrelic.cfg
file. They are repeated here to keep all of the .ini settings in one place. Each setting in newrelic.cfg
has its counterpart here, with newrelic.daemon.
as the prefix. For example, the ssl
setting in newrelic.cfg
is newrelic.daemon.ssl
in an .ini file.
Important
If the file /etc/newrelic/newrelic.cfg
exists, the agent ignores these settings, and the agent will not start the daemon automatically.
For more information about ways to start the daemon and when to use an external configuration file, see PHP daemon startup modes.
Scope: | SYSTEM |
---|---|
Type: | Time specification string; for example, |
Default: |
|
Sets the elapsed time after which an application will be considered inactive. Inactive applications do not count against the maximum limit of 250 applications. Allowed units are "ns"
, "us"
, "ms"
, "s"
, "m"
, and "h"
.
A value of 0
will be interpreted as "no timeout." This will result in new applications always counting towards the 250 application limit, as well as the daemon being unable to release a small amount of memory per application back to the operating system.
Recommendation: Do not use this value unless New Relic Support requests it. Instead, for occasional background transactions, use a value of twice the interval. For example, for an hourly background job, set the timeout to 2 hours.
Scope: | SYSTEM |
---|---|
Type: | Time specification string; for example, |
Default: |
|
Sets the maximum time the agent should wait for the daemon connecting an application. A value of "0"
causes the agent to only make one attempt at connecting to the daemon. Allowed units are "ns"
, "us"
, "ms"
, "s"
, "m"
, and "h"
.
With this timeout set, the agent will not immediately drop a transaction when the daemon hasn't connected to the backend yet, but rather grant the daemon time to establish the connection.
Recommendation: If setting a timeout, the recommended value is "15s"
. Only set this timeout when instrumenting long-lived background tasks, as in case of connection problems the agent will block for the given timeout at every transaction start.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
The setting specifies the name of an audit log, which will contain all of the data sent from the daemon to the New Relic servers, including the full URL, date, time, and the uncompressed, unencoded data for each request.
This file cannot be the same file as the daemon log.
Important
This audit log can become very large, very quickly. Avoid using the newrelic.daemon.auditlog
setting for extended periods of time. Its primary purpose is to allow system administrators to perform security reviews and to observe exactly what data transmits.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the name and optional port of the collector host which the daemon will contact to verify your and send agent data.
This is either just the name of the host or the name and port number in the form "hostname:port"
. Specifying a port number of 0
will use the default port, which is 80.
Caution
Do not change this value without guidance from New Relic Support.
Scope: | SYSTEM |
---|---|
Type: | Number |
Default: |
|
If you prefer to have the daemon launched externally before the agent starts up, this value determines when the agent is allowed to start the daemon:
0
: No restrictions are placed on daemon startup and the agent can start the daemon any time.1
: Non-command line (such as Apache or php-fpm) agents can start the daemon.2
: Only command line agents can start the daemon.3
: The agent will never start the daemon. Use this setting if you are configuring the daemon vianewrelic.cfg
and starting it outside of the agent.Important
If
/etc/newrelic/newrelic.cfg
exists, the agent assumes the daemon is meant to be started by its startup script, not via the agent. This setting has no meaning to and does not appear innewrelic.cfg
.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the name of the daemon executable to launch.
This variable identifies the full path to the daemon executable file. If the New Relic system was installed using the standard packages, the default location will be correct. If you have installed to a custom location using the tar distribution (and do not have permission to write to /usr/bin
), then the daemon may reside at another location.
This setting does not appear in the newrelic.cfg
file as it is only relevant to PHP.
Important
On OpenSolaris, /usr
is frequently a read-only file system. The default daemon location for OpenSolaris is /opt/newrelic/bin/newrelic-daemon
.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the name of the log file to record daemon specific log messages. This file must be writable by the daemon. The most common case is that the Apache user will end up starting the daemon when Apache itself starts up, thus you should ensure that the file is writable by whichever user runs the Apache process.
Caution
If the daemon log file is not writable, the daemon will not start automatically, which will prevent data from reporting.
You can use write permissions to this file as a means of restricting who can start the daemon.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the detail level for messages recorded to New Relic's daemon log file. Possible values, in increasing order of detail, are:
error
warning
info
healthcheck
debug
The more verbose settings can generate a lot of information very quickly.
healthcheck
logs the exact number of connected applications. When necessary, setdebug
for short periods of time to identify problems.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: | (depends on OS) |
Sets the name of the file in which the daemon will record its process ID (pid).
This file is used by the daemon startup and shutdown script to determine whether or not the daemon is already running.
Scope: | SYSTEM |
---|---|
Type: | String or Number |
Default: |
|
Tip
From v9.2.0.247, the PHP agent supports a new setting, newrelic.daemon.address
, which serves as an alias to newrelic.daemon.port
. You can use either to specify the location of the New Relic PHP daemon. If both values are set, newrelic.daemon.address
takes precedence.
Sets the socket endpoint for agent to daemon communications.
This can be specified in four ways.
To use a specified file as a UNIX domain socket (UDS), provide an absolute path name as a string. This is the default on non-Linux systems.
To use a standard TCP port, specify a number in the range 1 to 65534.
To use an abstract socket, use the value
@newrelic-daemon
(available for agent version 5.2.0.141 or higher). This is the default on Linux systems.To connect to a daemon that is running on a different host (helpful for container environments), set this value to
host:port
, wherehost
denotes either a host name or an IP, andport
denotes a valid port number. Both IPv4 and IPv6 are supported. This is available for agent version 9.2.0.247 or higher.Caution
Data transmitted from the agent to the daemon is not encrypted. The only exception to this is the SQL obfuscation that happens before sending data to the daemon. We recommend only using a private network connection between the agent and daemon (this only applies when the agent and daemon are running on different hosts).
If you use port numbers, Unix systems require that ports in the range 1 to 1023 require the daemon be run as the super-user. In case the daemon uses a non-standard port, this variable also sets the port number the agent will use for communicating with the daemon.
Important
If you're using the
newrelic.cfg
startup mechanism for the daemon, this setting and theaddress
setting in that file must match.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the host and user credentials to use as an egress proxy.
This is only used if your site requires a proxy in order to access the New Relic data collection servers. It can take any of the following forms, depending on the proxy setup:
hostname
hostname:port
user@hostname
user@hostname:port
user:password@hostname
user:password@hostname:port
proxytype://user:password@hostname:port
A proxy type of HTTP is assumed unless another proxytype is specified. In that case, proxytype can be one of http, socks4, socks4a, or socks5.
Scope: | SYSTEM |
---|---|
Type: | Boolean |
Default: |
|
This setting is ignored on PHP agent versions 8.0 and higher, and HTTPS will always be used to communicate with New Relic.
On versions of the PHP agent versions lower than 8.0, controls whether or not communication with New Relic collectors should use a secure HTTP connection. The agent communicates with New Relic via HTTPS by default, and New Relic requires HTTPS for all traffic to APM and the New Relic REST API.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the location of a file containing CA certificates in PEM format. When set, the certificates in this file will be used to authenticate the New Relic collector. In most cases it should not be necessary to configure a CA bundle. The New Relic PHP agent comes bundled with the necessary CA certificates.
If newrelic.daemon.ssl_ca_path
is also set, the certificates in this file will be searched first, followed by the certificates contained in the newrelic.daemon.ssl_ca_path
directory.
This setting has no effect when newrelic.daemon.ssl
is set to false
.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets the location of a directory containing trusted CA certificates in PEM format. When set, the certificates in this directory will be used to authenticate the New Relic collector. In most cases it should not be necessary to configure a CA path. The New Relic PHP agent comes bundled with the necessary CA certificates.
If newrelic.daemon.ssl_ca_bundle
is also set, it will be searched first followed by the certificates contained in newrelic.daemon.ssl_ca_path
.
This setting has no effect when newrelic.daemon.ssl
is set to false
.
Scope: | SYSTEM |
---|---|
Type: | Time specification string; for example, |
Default: |
|
Sets the maximum time the agent should wait for the daemon to start after a daemon launch was triggered. A value of "0"
causes the agent to not wait. Allowed units are "ns"
, "us"
, "ms"
, "s"
, "m"
and "h"
.
The specified timeout value will be passed to the daemon via the --wait-for-port
flag. This causes daemon startup to block until a socket is acquired or until the timeout is elapsed.
Recommendation: If setting a timeout, the recommended value is "2s"
to "5s"
. It is recommended to only set this timeout when instrumenting long-lived background tasks, as in case of daemon start problems the agent will block for the given timeout at every transaction start.
Logs in context
Starting with PHP agent version 10.1.0, support for APM logs in context has been added to the agent. As of version 10.3.0, the logging metrics and agent log forwarding features are enabled by default.
For some tips on configuring logs for the PHP agent, see Configure PHP logs in context.
Changing these settings in your local agent configuration file (newrelic.ini
) requires a restart of the webserver for them to take effect.
Important
Always restart your web server after changing INI settings. Otherwise, they may not take effect immediately.
An example configuration that enabled logs in context with logging metrics and agent log forwarding would be:
newrelic.application_logging.enabled = truenewrelic.application_logging.metrics.enabled = truenewrelic.application_logging.forwarding.enabled = true
The value newrelic.application_logging.enabled
controls if the logs in context feature is active or not.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Set to true
to enable the core logs in context feature. When enabled, additional logging framework instrumentation is enabled, whether or not logs are sent to New Relic.
Important
Agent release 10.1.0 has this feature enabled in the agent configuration file by default.
Set to false
to completely disable this feature, including the collection of log metrics and log forwarding.
If you're using a supported logging framework and want to use the agent to send your application logs to New Relic, you can control that through the newrelic.config.application_logging.forwarding
prefixed INI settings. Options available are:
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enables the sending of application logs to New Relic.
Important
Agent releases 10.3.0 and later have this feature enabled in the agent configuration file by default.
Using the log forwarding feature will increase your data ingest, which may affect your billing. For more information, see our documentation about tracking your data ingest.
If you have an existing log forwarding solution and are updating your agent to use automatic logs in context, be sure to disable your old log forwarder. Otherwise, your app will be sending double log lines. Depending on your account, this could result in double billing. For more information, follow the procedures to disable your specific log forwarder.
Set this to true
to have your logs sent to New Relic.
Set this to false
if you don't want your logs sent to New Relic.
When enabled
= true
, logs are forwarded directly from the PHP agent with linking metadata that allows our logs-in-context features to work. The PHP agent doesn't write any metadata into the application log output. When enabled
= false
, no log data is sent to New Relic and the application log output is unchanged.
Example configuration file (newrelic.ini
):
newrelic.application_logging.enabled = true
Scope: | PERDIR |
---|---|
Type: | Integer |
Default: |
|
Max: |
|
A positive integer specifying the maximum number of logs lines per minute to send.
Set this to 0
to effectively disable the sending of logs.
Set this to a lower value to reduce the amount of log lines sent (may cause log sampling). Set this to a higher value to send more log lines.
Each log receives the same priority as its associated transaction. Some logs may not be included because they are limited by max_samples_stored
. For example, if logging max_samples_stored
is set to 10,000 and a transaction 1 has 10,000 log entries, only log entries for transaction 1 will be recorded. If transaction 1 has less than 10,000 logs you receive all logs for transaction 1. If there is still space, you receive all the logs for transaction 2, and so on. Log entries with higher priorities are kept over those with lower priorities.
Tip
This refers to the number of logs sent per minute. Setting max_samples_stored
to a value less than 12 will have the effect of causing no logs to be sent.
Tip
Any non-negative integer is valid, but currently the maximum supported value is 20,000.
Example configuration file (newrelic.ini
):
newrelic.application_logging.forwarding.max_samples_stored = 10000
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
It is possible to control the log level of messages forwarded by the agent. The log levels recognized follow the PSR-3 specification and are as follows (from highest to lowest severity):
EMERGENCY
ALERT
CRITICAL
ERROR
WARNING
NOTICE
INFO
DEBUG
When a log level is specifed for the agent then all messages of this log level or of higher severity will be reported.
The agent will default to a log level of WARNING
.
Example configuration file (newrelic.ini
):
newrelic.application_logging.forwarding.log_level = "INFO"
The PHP agent can collect metrics related to log events for supported logging frameworks. The creation of these metrics is controlled by the newrelic.application_logging.metrics.enable
option:
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enables the capture of metrics information about your logs and log levels, which is displayed in a chart on the APM Summary page.
Leave this set to true to allow the agent to capture metric information about your logs.
Set this to false
to disable this feature.
Important
If you disable the collection of log metrics, the log chart on the summary page will appear blank.
Important
If you have an existing log forwarding solution and are updating your agent to use automatic logs in context, be sure to disable your manual log forwarder. Otherwise, your app will be sending double the log data. Depending on your account, this could result in double billing. For more information, follow the procedures to disable your specific log forwarder.
Transaction tracer .ini settings
The values of these settings are used to control transaction traces.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
Set this to a comma-separated list of user defined functions or methods to instrument:
"myfunction,myclass::method,otherfunction"
Internal PHP functions cannot have custom tracing.
You can add to the list of custom functions with each PERDIR file, but you cannot remove a function or method that has already been added. If you want to programmatically add functions or methods to be instrumented, use the newrelic_add_custom_tracer()
API function call.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enables or disables the transaction tracer.
The tracer creates a detailed transaction trace for transactions that take more time than the threshold, as set by the newrelic.transaction_tracer.threshold
value. Only one transaction trace per application per harvest cycle is stored and it is always the slowest transaction during that cycle.
Transaction traces are useful for diagnosing why a particular transaction was slow. Unless memory and performance are critical, they should almost never be disabled. Enabling this does have a very slight performance impact and does use more memory.
For more information, see newrelic.transaction_tracer.detail
.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enables or disables requesting explain plans from MySQLi and PDO MySQL libraries for slow query calls. Explain plans will only be available when newrelic.transaction_tracer.slow_sql
is set to true
and newrelic.transaction_tracer.record_sql
is not set to "off"
.
Scope: | PERDIR |
---|---|
Type: | Duration |
Default: |
|
Sets the threshold beyond which queries are considered "slow" and thus candidates for the Slow Queries page. Specify duration as an absolute value with units. Default unit is in milliseconds if none is specified.
Example durations
"200ms"
"1s250ms"
"1h30m"
"750us"
Scope: | SYSTEM |
---|---|
Type: | Boolean |
Default: |
|
Enables or disables support for tracing internal functions (that is, functions written in C and provided either via the PHP standard library or PECL extensions). When enabled, internal functions appear in transaction traces like functions written in PHP.
Enabling this option may result in transactions being slower, especially when collecting many traces from PHP 5.x. Enabling this option is only recommended when specifically debugging performance issues where an internal function is suspected to be slow.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
Sets how queries are recorded (if at all).
When recording transaction traces internally, the full query for slow query calls is recorded. Sending this query to New Relic can have serious security implications, so by default, all database statements are obfuscated before being sent to New Relic. The obfuscation is not reversible, as it replaces strings and numbers in any query with question marks. The only things that survive intact are field names, not any of their values.
If you are testing with data that is not sensitive and you need to see the raw queries in transaction traces, set this to
"raw"
.If you do not want queries recorded at all, set this to
"off"
.Important
Always set this back to
"obfuscated"
or"off"
in any production environment.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Use this setting to enable or disable the Slow Queries feature. When enabled, it will:
Record the top 10 slowest database queries per application per minute.
Create a stack trace leading up to the query.
If this variable is set to
false
or SQL recording is disabled, the New Relic agent does not gather any slow query data.
Scope: | PERDIR |
---|---|
Type: | Duration |
Default: |
|
This sets the threshold above which the agent will record the full PHP stack for transaction traces for which queries are being recorded.
Specify duration as an absolute value with units. Default unit is in milliseconds if none is specified.
Example durations
"200ms"
"1s250ms"
"1h30m"
"750us"
Stack traces can consume memory, so be careful of setting this value too low. This variable has no meaning if
newrelic.transaction_tracer.record_sql
is set to"off"
.
Scope: | PERDIR |
---|---|
Type: | Duration |
Default: |
|
Use this variable to set the threshold beyond which transactions are eligible for being traced. Available values include:
Use
"apdex_f"
to set the threshold to 4 times the application's apdex_t value. For more information, see Apdex: Measuring user satisfaction.Use any other duration string to set a specific time threshold. Specify the duration as an absolute value and the unit of measurement. If none is specified, the unit defaults to millisecond.
Example durations
"200ms"
"1s250ms"
"1h30m"
"750us"
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Use this setting to enable or disable gathering of DQL input queries with Slow Queries and Transaction Traces. When enabled, these will appear along with slow queries and transaction traces.
Scope: | PERDIR |
---|---|
Type: | Number |
Default: |
|
Specifies the maximum number of segments the PHP agent shall record for web transactions. Once that maximum is reached sampling will occur.
The PHP agent reports transaction traces and distributed traces as a collection of segments. Each segment represents a method or a function call in a transaction trace. The default value for this configuration is 0
, indicating that the PHP agent shall capture all segments during a web transaction. At the end of a transaction, it assembles the highest priority segments to report in a transaction trace.
For long-running PHP processes with hundreds of thousands or millions of function calls, setting this to a value greater than 1
prevents the PHP agent from exhausting system memory when recording segments.
Segment size can vary based upon the length of the corresponding method's name, the length of its class name, and the number of subsequent calls made by the method. That said, a conservative estimate is 400 bytes per segment. To limit the PHP agent to 40 MB for segment capture, set this value to 100000
. If this value is set lower than 2000
, it further limits the total number of segments reported for transaction traces.
This configuration setting is only for PHP web processes; it will not effect PHP CLI processes. To set a limit for CLI processes use newrelic.transaction_tracer.max_segments_cli
.
Scope: | PERDIR |
---|---|
Type: | Number |
Default: |
|
Specifies the maximum number of segments the PHP agent shall record for CLI transactions. Once that maximum is reached sampling will occur.
The PHP agent reports transaction traces and distributed traces as a collection of segments. Each segment represents a method or a function call in a transaction trace. The default value for this configuration is 100000
, indicating that the PHP agent shall capture all segments during a web transaction. At the end of a transaction, it assembles the highest priority segments to report in a transaction trace.
For long-running PHP processes with hundreds of thousands or millions of function calls, setting this to a value greater than 1
prevents the PHP agent from exhausting system memory when recording segments.
Segment size can vary based upon the length of the corresponding method's name, the length of its class name, and the number of subsequent calls made by the method. That said, a conservative estimate is 400 bytes per segment. To limit the PHP agent to 40 MB for segment capture, set this value to 100000
. If this value is set lower than 2000
, it further limits the total number of segments reported for transaction traces.
This configuration setting is only for PHP CLI processes; it will not effect PHP web processes. To set a limit for web processes use newrelic.transaction_tracer.max_segments_web
.
Other tracer .ini settings
The values of these settings are used to control various tracer features.
Important
Cross Application Tracing is deprecated and in PHP Agent version 9.21.0.311 has been disabled by default. We recommend the distributed tracing feature, which improves on cross application tracing.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enable or disable the cross application tracer. The cross application tracer inserts HTTP headers into outbound requests and the response in order to link together web transaction metrics and transaction traces between applications.
Distributed tracing and cross application tracing cannot be used simultaneously. The default configuration for the PHP agent enables distributed tracing and disables cross application tracing.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Important
Enabling distributed tracing disables cross-application tracing. Read the transition guide to understand effects on New Relic features.
Enable or disable distributed tracing. It is turned on by default in PHP agents 9.21.0 and higher. When the agent's transaction tracer and distributed tracing features are enabled, the agent will insert headers into outbound requests, and scan incoming requests for distributed tracing headers.
newrelic.transaction_tracer.enabled = truenewrelic.distributed_tracing_enabled = true
For more information, see Distributed tracing for your PHP services.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Set this to true to exclude the New Relic distributed tracing header that is attached to outbound requests, and to instead only rely on W3C Trace Context Headers for distributed tracing. If this is false then both types of headers are attached to outbound requests.
The New Relic distributed tracing header allows interoperability with older agents that do not support W3C Trace Context headers. Agent versions that support W3C Trace Context headers will prioritize them over New Relic headers for distributed tracing.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Span events are reported for distributed tracing. Span event reporting requires distributed tracing to be enabled. This option enables/disables the reporting of span events.
Scope: | PERDIR |
---|---|
Type: | Integer |
Default: |
|
Span events are reported for distributed tracing. This value sets the maximum number of span events sent to the collector per harvest cycle. A value of 0
will use the agent default of 2000
. The maximum setting is 10000
.
Scope: | PERDIR |
---|---|
Type: | String |
Default: |
|
Configures the Trace Observer used for Infinite Tracing. If empty, Infinite Tracing support will be disabled. This requires distributed tracing and span events to be enabled.
Scope: | PERDIR |
---|---|
Type: | Integer |
Default: |
|
Configures the TCP/IP port used to communicate with the Infinite Tracing Trace Observer. This setting is ignored if newrelic.infinite_tracing.trace_observer.host
is empty. This setting will not usually need to be changed.
Scope: | PERDIR |
---|---|
Type: | Integer (1000 or higher) |
Default: |
|
Sets the number of span events that can be queued for transmission to the Infinite Tracing Trace Observer. The agent internally manages span events for Infinite Tracing in span batches. Those span batches can hold a maximum of 1000 spans. Therefore, the span events queue size cannot be lower than 1000
, as otherwise not even a single span batch can be queued. If a queue size lower than 1000 is specified, the minimum size of 1000
is used.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enable or disable the error collector. When enabled, the agent collects and reports PHP errors to the New Relic UI.
The agent records only the single most severe error for each transaction, and up to 20 errors per harvest cycle.
Tip
For an overview of error configuration in APM, see Manage errors in APM.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
When enabled, the agent collects errors returned by MySQL functions as if they were PHP errors.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Set this to true
to assign the highest priority to errors identified through the newrelic_notice_error()
API function.
Scope: | PERDIR |
---|---|
Type: | String |
Default: | (none) |
A comma separated list of fully-qualified exception class names that the agent should ignore. When an unhandled exception occurs, the agent will perform the equivalent of $exception instanceof Class
for each of the classes listed. If any of those checks returns true, the agent will not record an exception.
Depending on the supported PHP release, these values are equivalent to disabling exception reporting:
- Supported PHP 5 versions:
newrelic.error_collector.ignore_exceptions = Exceptions
- Supported PHP 7 versions:
newrelic.error_collector.ignore_exceptions = Throwable
Scope: | PERDIR |
---|---|
Type: | Integer or a bitwise expression of PHP-defined error constants |
Default: |
|
Sets the error levels for the PHP agent to ignore. The value for this setting uses similar syntax to PHP's error_reporting
option. For example, to configure the PHP agent to ignore E_WARNING
and E_ERROR
level errors, use:
newrelic.error_collector.ignore_errors = E_WARNING | E_ERROR
or
newrelic.error_collector.ignore_errors = 3
To configure the PHP agent to ignore everything but E_WARNING
, use:
newrelic.error_collector.ignore_errors = E_ALL & ~E_WARNING
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Notes: | In agents prior to version 3.0 the default for this value was |
To enable Drupal module tracking, set this to true
. This option has the same performance impact as newrelic.transaction_tracer.detail
. It will enable the recording of Drupal module functions and call counts, and they will display under the Modules tab, much like web transactions.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
To enable WordPress hook tracking, set this to true
. It will enable the recording of WordPress hooks, plugins, and themes, and they will display under the WordPress tab in the New Relic UI.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
This is the same as newrelic.webtransaction.name.functions
, except it uses file names to name the web transaction. The file names can be standard POSIX regular expression to be used with PCRE; for example, "controllers/actions/.*"
.
Scope: | PERDIR |
---|---|
Type: | String (use quotes) |
Default: |
|
Unless the New Relic agent detects a specific framework, such as Drupal or Wordpress, web transactions are named after the initial PHP file; for example, article.php
.
When the initial file is a dispatcher, this naming scheme produces less than useful data. Use this variable to specify a list of functions that are the "actions" generated by the dispatcher. The name of the web transaction will be the first action function executed.
Example dispatch function naming
If index.php
dispatches to functions named:
login
,logout
,admin
,show
, andedit
You would set this value to
"login,logout,admin,show,edit"
.The web transactions will be named
login
,logout
, etc. instead of/index.php
(the initial file name).
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
When enabled,this removes any content in the request URI after the script name. For example, this would remove the trailing /xyz/zy
from /path/to/foo.php/xyz/zy
.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
If false
, the agent will not report datastore instance metrics, nor add host
or port_path_or_id
parameters to transaction or slow sql traces.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
If false
, the agent will not add database_name
parameter to transaction or slow sql traces.
Attribute settings
This section lists the settings that affect attribute collection and reporting.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enable or disable the collection of attributes generated by the PHP agent or generated by the user through newrelic_add_custom_parameter()
. This setting will take precedence over all other attribute configuration settings.
For more information, see Enabling and disabling attributes.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Control which destinations receive attributes. These configuration settings will override the .include
and .exclude
settings.
For more information on the destinations available, see Enabling and disabling attributes.
Scope: | PERDIR |
---|---|
Type: | String |
Default: | (none) |
This is a family of configuration options that allow fine control over the destinations of attributes. For more information, see Enabling and disabling attributes.
Custom events
This section lists the settings that affect custom event reporting.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enable or disable the collection of events generated by the the user through newrelic_record_custom_event()
. This setting will take precedence over all other attribute configuration settings.
For more information, see Report custom events and attributes.
Scope: | PERDIR |
---|---|
Type: | Integer |
Default: |
|
Max: |
|
A positive integer specifying the maximum number of custom events per minute to send.
Setting this to 0
will effectively disable the sending of custom events. Setting newrelic.custom_insights_events.enabled
is the preferred way to enable or disable custom event generation.
Set this to a lower value to reduce the amount of custom events sent (may cause custom event sampling). Set this to a higher value to send more custom events lines.
Important
The newrelic.custom_events.max_samples_stored
INI variable was added in the 10.4.0.316 release.
Code-level metrics
This section lists the settings that affect the reporting of code-level metrics.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enable or disable the collection of code-level metrics.
Important
The newrelic.code_level_metrics.enabled
INI variable was added in the 10.4.0.316 release and was disabled by default.
Code-level metrics are enabled by default starting with version 10.6.0.
Important
This can only be set through an environment variable.
Type | Integer |
---|---|
Default | (none) |
Environment variable |
The commit sha. The entire sha can be used or just the first seven characters (e.g., 734713b).
Important
This can only be set through an environment variable.
Type | String |
---|---|
Default | (none) |
Environment variable |
A release tag (such as v0.1.209 or release-209).
Other .ini settings
This section lists the remaining newrelic.ini settings.
Scope: | SYSTEM |
---|---|
Type: | Boolean |
Default: | (none) |
Enable or disable the New Relic agent. By default the New Relic PHP agent is enabled for all directories.
If you have multiple sites on your web server but only want the PHP agent to monitor specific ones:
Make sure
newrelic.enabled
is set totrue
at the global (SYSTEM) level in yournewrelic.ini
file.Set
newrelic.enabled
tofalse
for one or more specific sites on a per-directory basis (PERDIR).If you need to disable the agent globally, set the
newrelic.enabled
value tofalse
in thenewrelic.ini
file.When the agent is globally disabled, it does not initialize completely. It assumes you are globally disabling it for a critical reason, and the agent will attempt to have as close to zero impact on PHP as possible.
Important
You cannot globally disable the agent and then selectively enable it on a per-directory basis by using
.htaccess
.
Scope: | SYSTEM |
---|---|
Type: | String (use quotes) |
Default: |
|
This identifies the file name for logging messages. This is useful for debugging any issues with the agent. Whatever you set this to, ensure that:
- The permissions for the containing directory and the file itself are correct.
- The user that PHP runs as can write to the file. Usually this is the same user as the web server.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
When set to true
, the agent will collect and report analytics event data. Event data allows the New Relic UI to show additional information such as histograms and percentiles.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
When set to true
, the agent will collect and report error event data. Event data allows the New Relic UI to show Error analytics.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
This setting enables new and experimental features within the PHP agent. These flags are used to selectively enable features that are intended to be enabled by default in later versions of the PHP agent.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
This enables auto-insertion of the JavaScript fragments for browser monitoring. When enabled will cause the agent to insert a header and a footer in HTML output that will generate metrics on page load timing for the end-user experience. For more information, see Page load timing in PHP.
Scope: | PERDIR |
---|---|
Type: | Boolean |
Default: |
|
Enables or disables support for the Guzzle library when used with New Relic.
- PHP agent version 6.4 or higher: This setting is set to
true
by default.
Scope: | SYSTEM |
---|---|
Type: | Boolean |
Default: |
|
Notes: | Introduced in PHP agent version 9.4 |
Enables the detection of frameworks and libraries when preloading is enabled. Preloading was introduced in PHP version 7.4. newrelic.preload_framework_library_detection
will only take effect when opcache.preload
is set in the php.ini
file.