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:
<?phpphpinfo();?>
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.
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 newrelic.ini file.
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:
For true or enabled: on, true, the number 1.
For false or disabled: off, false, the number 0.
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.
w\= weeks
d\= days
h\= hours
m\= minutes
s\= seconds
ms\= milliseconds
us\= microseconds
Example durations:
"1w3d23h10m"\= 1 week, 3 days, 23 hours, and 10 minutes
"5h30m"\= 5 hours and 30 minutes
"500"\= 500 milliseconds
General configuration settings
These settings are available in the newrelic.ini file.
Scope:
PERDIR
Type:
String (use quotes)
Default:
"PHP Application"
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:
false
Caution
This setting has been deprecated and may not behave as expected. Instead, use attribute properties.
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.
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:
"info"
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 at verbosedebug 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:
1
Notes:
This used to be newrelic.transaction_tracer.top100.
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 using newrelic.transaction_tracer.custom.
The default level of 1 does have a performance impact. If you need to improve performance, try setting the detail level to 0.
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:
false
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.
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.
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, "5m" or "1h20m"
Default:
"10m"
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, "1s" or "5m"
Default:
"0"
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:
"collector.newrelic.com"
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:
0
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 via newrelic.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 in newrelic.cfg.
Scope:
SYSTEM
Type:
String (use quotes)
Default:
"/usr/bin/newrelic-daemon"
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:
"/var/log/newrelic/newrelic-daemon.log"
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:
"info"
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, set debug 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:
"@newrelic" on Linux, "/tmp/.newrelic.sock" otherwise
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, where host denotes either a host name or an IP, and port 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 the address 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:
true
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.
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.
Time specification string; for example, "1s" or "5m"
Default:
"0"
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
PHP agent version 10.1.0 lets you forward your PHP logs with APM logs in context. As of version 10.3.0, the logging metrics and agent log forwarding features are enabled by default. The value newrelic.application_logging.enabled controls whether or not the logs in context feature is active or inactive.
Keep in mind that changing your settings in your local agent configuration file (newrelic.ini) requires a restart of the web server for them to take effect. If you don't, the changes may not take effect immediately.
Scope:
PERDIR
Type:
Boolean
Default:
true
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.
Set to false to completely disable this feature, including the collection of log metrics and log forwarding.
Logs in context is now enabled by default. If you've disabled this feature, then make sure to restart your app or your changes will not take effect immediately.
If you're using a supported logging framework, you can direct the agent to forward your app logs to New Relic.
newrelic.application_logging.forwarding.enabled enables or disables log forwarding
newrelic.application_logging.forwarding.max_samples_stored limits how many logs your app forwards to New Relic
newrelic.application_logging.forwarding.log_level lets you choose what kinds of logs your app forwards to New Relic
Scope:
PERDIR
Type:
Boolean
Default:
true
Enables the sending of application logs to New Relic.
Set this to true to have your logs sent to New Relic. This forwards logs 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.
Set this to false if you don't want your logs sent to New Relic. When enabled is set to 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
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.
Important
Using the log forwarding feature increases your data ingest, which may affect your billing. For more information, see our documentation about tracking your data ingest.
Scope:
PERDIR
Type:
Integer
Default:
10000
Max:
20000
Set the value to a positive integer to specify the maximum number of log 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. This 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. Any non-negative integer is valid, but currently the maximum supported value is 20,000.
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 specified for the agent, all messages of this log level and higher will be reported. For example, if you set your log level to ALERT, then you will receive logs for the ALERT and EMERGENCY severity. The default log level is WARNING.
The PHP agent captures context data for the Monolog library and adds that context as attributes to your forwarded logs. You can control what context your agent adds through settings under the context_data section, within the forwarding section.
newrelic.application_logging.forwarding.context_data.enabled adds context data from Monolog to your logs attributes
newrelic.application_logging.forwarding.context_data.include defines what attribute keys are found in your forwarded logs
newrelic.application_logging.forwarding.context_data.exclude defines what attributes keys are excluded in your forwarded logs
Type
Boolean
Default
false
Set this to true to add context data as logs attributes.
Set this to false if you don't want context data added as attributes to your logs.
Type
List of strings
Default
(none)
When you apply attribute rules to log context attributes, the include rule drops all attributes not defined in the ruleset. This is a different behavior from other types of agent attributes.
If log context attributes are not appearing as expected, then you should review the newrelic.attributes.include ruleset to confirm that the missing attributes are part of the exclusion. We recommend that you set newrelic.loglevel=verbosedebug to enable verbose log messages from the agent, too. Once that's updated, look for messages from the agent about excluded attributes. This can clue you in on how to adjust the include/exclude rules.
If context_data is enabled for log forwarding, all attribute keys found in this list will appear in log records. An empty list will send all attribute keys as a default.
If all include lists are empty then all log context attributes are forwarded.
Type
List of strings
Default
(none)
If context_data is enabled for log forwarding, all attribute keys found in this list are excluded from log records.
Leaving this field empty results in default behavior. Attributes may still be excluded if an include rule exists.
The PHP agent only forwards log context data that has a string key and a value, which is a string or a scalar (int, double, boolean).
Log decoration
The PHP agent can collect also add linking metadata to Monolog log records to allow logs in context to work with log data forwarded by a 3rd party log forwarder. To enable this feature use the the newrelic.application_logging.local_decorating.enable option:
Scope:
PERDIR
Type:
Boolean
Default:
false
This enables the addition of linking metadata to Monolog log records. Set this to true to enable this feature. Leave this set to false if using the APM log forwarding feature to forward your logs to New Relic.
Important
The log decoration feature first appears in PHP agent release 10.13.0.1.
The log decoration feature requires additional steps to ensure the linking metadata is contained in the log messages. See the
(PHP logs in context)[/docs/logs/logs-context/configure-logs-context-php] page for more information on using this feature.
If you enable both log forwarding and log decorating then it will very likely cause your logs to be sent to New Relic in duplicate.
Log metrics
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:
true
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:
true
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.
Sets the threshold beyond the queries that 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:
false
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:
"obfuscated"
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:
true
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:
"500"
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:
"apdex_f"
Use this variable to set the threshold beyond which transactions are eligible for being traced. Available values include:
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:
true
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:
0
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:
100000
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:
false
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.
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.
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:
true
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:
0
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:
443
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:
100000
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:
true
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.
When enabled, the agent collects errors returned by MySQL functions as if they were PHP errors.
Scope:
PERDIR
Type:
Boolean
Default:
false
Set this to true to assign the highest priority to errors identified through the newrelic_notice_error() API function.
Note: Any uncaught errors will be assigned an even higher priority so these will take precendence over errors reported 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:
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:
In agents prior to version 3.0 the default for this value was false. Setting this option implied newrelic.transaction_tracer.detail = 1.
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:
true
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
Default:
"plugin_callbacks"
Sets the options how WordPress hooks are instrumented.
New Relic agent can provide different levels of insights into WordPress hooks.
By default, only plugin/theme callbacks are instrumented ("plugin_callbacks").
At the cost of increased agent's overhead it is possible to extend the
instrumentation to all hook callbacks functions ("all_callbacks"). Third option
is to monitor hooks without instrumenting callbacks ("threshold"). This option
does not give insights about plugins/themes. Read more about WordPress specific
instrumentation here.
Scope:
PERDIR
Type:
Duration
Default:
1ms
Sets the threshold above which the New Relic agent will record WordPress hook execution. Used when newrelic.framework.wordpress.hooks.options is set to "threshold".
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, and
edit
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:
false
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:
true
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:
true
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:
true
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.
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:
true
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.
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:
true
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.
Setting one of the following tags will help you identify which versions of your software are producing the errors.
NEW_RELIC_METADATA_SERVICE_VERSION will create tags.service.version on event data containing the version of your code that is deployed, in many cases a semantic version such as 1.2.3, but not always.
NEW_RELIC_METADATA_RELEASE_TAG will create tags.releaseTag on event data containing the release tag (such as v0.1.209 or release-209).
NEW_RELIC_METADATA_COMMIT will create tags.commit on event data containing the commit sha. The entire sha can be used or just the first seven characters (e.g., 734713b).
An upcoming release of errors inbox will automatically track which versions of your software are producing errors. Any version data will also be displayed in CodeStream.
Vulnerability management settings
This section lists the settings that affect the reporting of PHP packages.
Scope:
PERDIR
Type:
Boolean
Default:
true
Notes:
Introduced in PHP agent version 10.17
When set to true, the agent will send up package detection information that can be viewed on the environment page.
Scope:
PERDIR
Type:
Boolean
Default:
false
Notes:
Introduced in PHP agent version 11.2
When set to true, the agent will try using Composer's runtime API for package detection.
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 to true at the global (SYSTEM) level in your newrelic.ini file.
Set newrelic.enabled to false 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 to false in the newrelic.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:
"/var/log/newrelic/php_agent.log"
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:
true
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:
true
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:
true
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:
true
This enables auto-insertion of the JavaScript fragments for . 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.
PHP agent version 6.4 or higher: This setting is set to true by default.
Scope:
SYSTEM
Type:
Boolean
Default:
true
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.
