PHP agent configuration

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 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.

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.

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"

• "joomla"

• "kohana"

• "laravel"

• "magento"

• "magento2"

• "mediawiki"

• "silex"

• "symfony1"

• "symfony2" (for Symfony 2 and 3)

• "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.

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.

Sets the New Relic license key to use. In a multi-tenant system this can be set on a per-directory basis.

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.

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.

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 and newrelic_set_user_attributes API function will have no effect, and they will return false.

• 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.

Adds tags.

Example tags

"Server:One;Data Center:Primary"

Sets the hostname to be displayed in the APM UI. If set, this overrides the default hostname that the agent captures automatically.

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.

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.

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.

Sets the name and optional port of the collector host which the daemon will contact to verify your license key 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.

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.

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.

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.

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

• debug

  The more verbose settings can generate a lot of information very quickly. When necessary, set debug for short periods of time to identify problems.

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.

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.

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.

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.

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.

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.

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.

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".

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"

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.

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.

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.

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".

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"

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.

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.

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 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 CLI processes; it will not effect PHP web processes. To set a limit for web processes use newrelic.transaction_tracer.max_segments_web.

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.

newrelic.transaction_tracer.enabled = true
newrelic.distributed_tracing_enabled = true

For more information, see Distributed tracing for your PHP services.

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.

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.

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.

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.

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.

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.

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.

Set this to true to assign the highest priority to errors identified through the newrelic_notice_error() API function.

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

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

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.

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.

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/.*".

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).

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.

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.

If false, the agent will not add database_name parameter to transaction or slow sql traces.

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.

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.

This is a family of configuration options that allow fine control over the destinations of attributes. For more information, see Enabling and disabling attributes.

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:

1. Make sure newrelic.enabled is set to true at the global (SYSTEM) level in your newrelic.ini file.

2. 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.

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.

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.

When set to true, the agent will collect and report error event data. Event data allows the New Relic UI to show Error analytics.

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.

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.

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.

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.