PHP agent (newrelic.ini) settings

The New Relic 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: Avoid changing the default settings unless you need to address very specific problems or circumstances. Take caution when changing these values, as they can increase the overhead of the agent, in some cases significantly.

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 set or modified.

The three types of scope are:

  • SYSTEM: Values set globally in the global .ini file.
  • PERDIR: Values set on a per-directory basis.
  • SCRIPT: Values set programmatically using the ini_set(); PHP function.

Each can also be set at a more general level. Valid locations for each are:

Can be set for: SYSTEM PERDIR SCRIPT
Set in the global .ini file. Yes Yes Yes
Set on a per-directory basis. Yes Yes
Programmatically with ini_set();. Yes

Note: Setting SCRIPT variables using the ini_set(); PHP function, may not always have the desired effect. If you make a call to ini_set(); after the value has been read and used by the agent, changing it will have no effect. It only checks after the flag has been set.

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, and 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 characters 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

Examples:

  • "1w3d23h10m"= 1 week, 3 days, 23 hours, and 10 minutes
  • "5h30m"= 5 hours and 30 minutes
  • "500"= 500 milliseconds

Commonly used .ini settings

This is a summary of the most commonly edited .ini settings and their permissible values.

newrelic.appname
Scope:PERDIR
Type:String (use quotes)
Default:"PHP Application"

Sets the name of the application that metrics will be reported into. This is how it will be seen in the New Relic UI.

Data for all applications with the same name will be merged in the New Relic UI, so set this carefully.

This value can be a semi-colon list of up to 3 application names. The first name in the list is the primary application name. It must be unique for each account / license key.

The application name is used as a key into a cache. When using multiple application names, only the first application name is taken into account for caching. Therefore, each application name can only appear as the first element once.

Example:

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, for instance, because you want to track a superset of applications, set the common application name in the second or third position, newrelic.appname="App2;App1" and newrelic.appname="App3;App1".

newrelic.capture_params
Scope:SCRIPT
Type:Boolean
Default:false

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 drop-down when displaying transaction traces.

If you pass sensitive information around directly in the URL, then its a good idea to keep this disabled.

Note: To set this value programmatically, use the newrelic_capture_params() API call. Do not use ini_set().

newrelic.framework
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 can be used to manually set the framework if auto-detection detects multiple frameworks.

Use any of the following values, as appropriate:

  • "cakephp"
  • "codeigniter"
  • "drupal" (for Drupal 6 and 7)
  • "drupal8"
  • "joomla"
  • "kohana"
  • "laravel"
  • "magento"
  • "mediawiki"
  • "symfony"
  • "symfony2"
  • "wordpress"
  • "yii"
  • "zend"
  • "no_framework" (to force no framework even if one was detected)

Note: If the framework auto-detection fails, this command will also fail.

newrelic.ignored_params
Scope:SCRIPT
Type:String (use quotes)
Default:""

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.

newrelic.license
Scope:PERDIR
Type:String (use quotes)
Default:""
Notes:Introduced in agent version 3.0.

Sets the New Relic license key to use.

In a multi-tenant system this can be set on a per-directory basis.

Note: If you have upgraded from a version of the agent prior to 3.0, the license that used to be set in the daemon configuration file will have been removed (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 .ini file. Delete the upgrade_please.key file.

newrelic.loglevel
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 it is best not to keep the agent at this level for longer than it takes to reproduce the problem you are experiencing. For more information about changing this setting, see Troubleshooting.

When reporting any agent issues to New Relic technical support, the support engineer may ask you to set this to a custom level, enabling debugging only for certain subsystems. The details of all the permutations of this option are beyond the scope of this document.

newrelic.transaction_tracer.detail
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 detail level is 1. This does have a performance impact. If you need to 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, only certain functions (defined internally by the agent) are instrumented. Even when reporting all calls, there may be uninstrumented time in the traces.

For more information, see uninstrumented time.

Daemon .ini settings

The values of these settings are used to 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, and are repeated here to keep all of the .ini settings in one place. Each setting in newrelic.cfg has its counterpart here, but prefixed with newrelic.daemon., For example, the ssl setting in newrelic.cfg is newrelic.daemon.ssl in an .ini file.

Note: If the file /etc/newrelic/newrelic.cfg exists, these settings will be ignored, and the agent will not start the daemon automatically.

See the section on PHP Daemon Startup Modes for more details on ways to start the daemon and when to use an external configuration file.

newrelic.daemon.auditlog
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, un-encoded data for each request.

This file can not be the same file as the daemon log.

This audit log can become very large, very quickly, so it is not recommended that you use it for extended periods of time. The primary purpose is to allow system administrators to perform security reviews and to observe exactly what data is sent over the wire.

This feature was introduced in version 3.4 of the New Relic agent.

newrelic.daemon.collector_host
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 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.

Caution: Do not change this value unless instructed to by New Relic technical support staff.

newrelic.daemon.dont_launch
Scope:SYSTEM
Type:Number
Default:0

If you prefer to have the daemon launched externally before the agent starts up, set this variable to non-zero.

The 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 (i.e., Apache / 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.

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

newrelic.daemon.location
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.

Note: On OpenSolaris, /usr is frequently a read-only file system. The default daemon location for OpenSolaris is /opt/newrelic/bin/newrelic-daemon.
newrelic.daemon.logfile
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.

Note: You can use write permissions to this file as a means of restricting who can start the daemon.

newrelic.daemon.loglevel
Scope:SYSTEM
Type:String (use quotes)
Default:"info"

Sets the level of detail of messages sent to the daemon log file. Possible values, in increasing order of detail, include:

  • error
  • warning
  • info
  • verbose
  • debug
  • verbosedebug

The more verbose settings can generate a lot of information very quickly. debug and verbosedebug should only be used for short periods of time to identify problems.

newrelic.daemon.pidfile
Scope:SYSTEM
Type:String (use quotes)
Default:Varies depending 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.

newrelic.daemon.port
Scope:SYSTEM
Type:String or Number
Default:"/tmp/.newrelic.sock"

Sets the socket endpoint for agent to daemon communications.

This can be specified in two ways.

  • To use a specified file as a UNIX domain socket (UDS), provide an absolute path name as a string. This is the preferred mechanism.
  • To use a standard TCP port, specify a number in the range 1-65534.

If you use port numbers, Unix systems require that ports in the range 1 - 1023 require the daemon be run as the super-user. In case the daemon is uses a non-standard port, this variable also sets the port number the agent will use for communicating with the daemon.

Note: If you are using the newrelic.cfg startup mechanism for the daemon then this setting and the port setting in that file must match.

newrelic.daemon.proxy
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 use 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
newrelic.daemon.ssl
Scope:SYSTEM
Type:Boolean
Default:true

Controls whether or not communication with New Relic data collectors should use a secure HTTP connection.

Set this to false to disable use of the secure HTTPS protocol when communicating with the New Relic data collectors.

newrelic.daemon.ssl_ca_bundle
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 servers. 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 (see below), 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.

newrelic.daemon.ssl_ca_path
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 servers. 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 (see above), 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.

Transaction tracer .ini settings

The values of these settings are used to control transaction traces.

Note: Your New Relic license defines whether or not the transaction tracing feature is available.

newrelic.transaction_tracer.capture_attributes
Scope:PERDIR
Type:Boolean
Default:true

This is set to attach custom parameters created using newrelic_add_custom_parameter to transaction traces. Set to false to disable attribute capture by this method.

newrelic.transaction_tracer.custom
Scope:PERDIR
Type:String (use quotes)
Default:""

Set this to a comma-separated list of user defined functions or methods to instrument.

Example: "myfunction,myclass::method,otherfunction"

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.

Note: Internal PHP functions cannot have custom tracing.

newrelic.transaction_tracer.enabled
Scope:SCRIPT
Type:Boolean
Default:true

Note: Your New Relic license defines whether or not the transaction tracing feature is available.

Enables or disables the transaction tracer.

This tracer records detailed information for slow transactions, where "slow" is defined as taking more time than 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. They should almost never be disabled (unless memory and performance are critical). Enabling this does have a very slight performance impact and does use more memory.

For more information, see newrelic.transaction_tracer.detail in this document.

newrelic.transaction_tracer.explain_threshold
Scope:SCRIPT
Type:Duration
Default:"500"

Sets the threshold beyond which SQL statements are considered "slow" and thus candidates for the Slow SQL tab.

Specify duration as an absolute value with units. Default unit is in milliseconds if none is specified.

Examples:

  • "200ms"
  • "1s250ms"
  • "1h30m"
  • "750us"
newrelic.transaction_tracer.record_sql
Scope:SCRIPT
Type:String (use quotes)
Default:"obfuscated"

Sets how SQL statements are recorded (if at all).

When recording transaction traces internally, the full SQL for slow SQL calls is recorded. Sending this SQL to New Relic can have serious security implications, so by default, all SQL statements are obfuscated before being sent to New Relic. The obfuscation is not reversible, as it replaces strings and numbers in any SQL command with question marks. The only things that survive intact are table and field names, not any of their values.

  • If you are testing with data that is not sensitive and you need to see the raw SQL in transaction traces, set this to "raw".
  • If you do not want SQL recorded at all, set this to "off".

Important: Always set this back to "obfuscated" or "off" in any production environment.

newrelic.transaction_tracer.slow_sql
Scope:SCRIPT
Type:Boolean
Default:true

Use this setting to enable or disable the "slow SQL" feature. When enabled, it will:

  • Record the top 10 slowest SQL calls per application per minute.
  • Create a stack trace leading up to the SQL statement.

If this variable is set to false or SQL recording is disabled, the New Relic agent does not gather any slow SQL data.

newrelic.transaction_tracer.stack_trace_threshold
Scope:SCRIPT
Type:Duration
Default:"500"

This sets the threshold above which the agent will record the full PHP stack for transaction traces for which SQL is being recorded.

Specify duration as an absolute value with units. Default unit is in milliseconds if none is specified.

Examples:

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

newrelic.transaction_tracer.threshold
Scope:SCRIPT
Type:Duration
Default:"apdex_f"

Use this variable to set the threshold beyond which transactions are considered "slow". Available values include:

  • Use "apdex_f" to use a value of 4 times the application's apdex_t value (defined in the New Relic UI under Application Settings).
  • Use any other duration string to set a specific duration as below.

Specify duration as an absolute value with units. Default unit is in milliseconds if none is specified.

Examples:

  • "200ms"
  • "1s250ms"
  • "1h30m"
  • "750us"

Other tracer .ini settings

The values of these settings are used to control various tracer featuress.

Note: Your New Relic license defines whether or not the tracer feature is available.

newrelic.cross_application_tracer.enabled
Scope:PERDIR
Type:Boolean
Default:true

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.

For more information, see Cross application traces.

newrelic.error_collector.capture_attributes
Scope:PERDIR
Type:Boolean
Default:true

This is set to attach custom parameters created using newrelic_add_custom_parameter to traced errors. Set to false to disable attribute capture by this method.

newrelic.error_collector.enabled
Scope:SCRIPT
Type:Boolean
Default:true

Note: Your New Relic license defines whether or not the error collector feature is available.

Enable or disable the error collector.

When enabled, the agent collects and reports PHP errors to the New Relic UI.

Please note that only the single most severe error is recorded for each transaction, and that only 20 errors per harvester cycle are recorded.

newrelic.error_collector.record_database_errors
Scope:SCRIPT
Type:Boolean
Default:true

Note: Error collection must also be enabled for this and the account subscription level must permit error collection.

Currently, this feature supports MySQL.

When enabled, errors returned by MySQL functions to be treated as if they were PHP errors, and thus subject to error collection.

newrelic.error_collector.prioritize_errors
Scope:PERDIR
Type:Boolean
Default:false

Note: Error collection must also be enabled for this and the account subscription level must permit error collection.

Set this to true then assign the highest priority to errors identified through the New Relic API.

newrelic.framework.drupal.modules
Scope:PERDIR
Type:Boolean
Default:true
Notes: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.

newrelic.webtransaction.name.files
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/.*".

newrelic.webtransaction.name.functions
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: If index.php dispatches to functions named

  • login,
  • logout,
  • admin,
  • show, and
  • edit,
then 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).

newrelic.webtransaction.name.remove_trailing_path
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.

Other .ini settings

This section lists the remaining newrelic.ini settings.

Note: Some of these settings have the potential for adding significant overhead to the PHP agent. New Relic strongly discourages you from modifying these settings unless New Relic Support asks you to do so.

newrelic.enabled
Scope:SYSTEM
Type:Boolean
Default:true

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. Note: You cannot globally disable the agent and then selectively enable it on a per-directory basis by using .htaccess.

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.

newrelic.logfile
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)
newrelic.analytics_events.capture_attributes
Scope:PERDIR
Type:Boolean
Default:true

This is set to attach custom parameters created using newrelic_add_custom_parameter to transaction analytic events. Set to false to disable attribute capture by this method.

newrelic.analytics_events.enabled
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.

Introduced in version 4.0 of the PHP agent.

newrelic.browser_monitoring.auto_instrument
Scope:SYSTEM
Type:Boolean
Default:true

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.

newrelic.browser_monitoring.capture_attributes
Scope:PERDIR
Type:Boolean
Default:false

Set to true to attach custom parameters created using newrelic_add_custom_parameter to transaction analytic events. Set to false to disable attribute capture by this method.

Note: When enabled, this obfuscates the custom parameters and puts them into the Javascript for page load timing (sometimes referred to as real user monitoring or RUM) that is injected into pages.

For more help

Additional documentation resources include:

  • New Relic for PHP (information about compatibility and requirements, basic instructions on how to install and configure the PHP agent, and links to more detailed information)
  • Per-directory .ini Settings (configuration settings for Apache, php-fpm, API calls, nginx, and roll-up application names)
  • Proxy Daemon (newrelic.cfg) Settings (configuration settings for the PHP proxy daemon when it is not started automatically by the agent)

If you need additional help, get support at support.newrelic.com.