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.
Always restart your web server after changing INI settings. Otherwise, they may not take effect immediately.
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.
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
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.inifile. This is usually the default if you have installed or compiled PHP yourself with no special options.
- Scan a given directory for all
If you are unsure which file to edit:
From the command line, review the output of
In a browser, review the output of a page containing the script:<?php phpinfo(); ?>
newrelic.inifile appears, use it.
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
- PERDIR: Values set on a per-directory basis.
Each can also be set at a more general level. Valid locations for each are:
Can be set for:
Set in the global
Set on a per-directory basis.
You cannot use
ini_set() for New Relic settings.
Each variable for your
newrelic.ini file has a defined type. The type specifies the syntax for the value you use.
Formatting and contents
String values can contain any alphanumeric character and punctuation. The value is delimited by quotes.
A logical true or false setting. Valid values are:
Numeric values can only contain digits, plus a period to indicate floats. Unless otherwise stated, all numbers are integers, not floats.
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.
These settings are available in the
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.daemon.ssl in an .ini file.
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.
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 18.104.22.168 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
hostdenotes either a host name or an IP, and
portdenotes a valid port number. Both IPv4 and IPv6 are supported. This is available for agent version 22.214.171.124 or higher.
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.
If you're using the
newrelic.cfgstartup mechanism for the daemon, this setting and the
addresssetting in that file must match.
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
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
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.
The values of these settings are used to control transaction traces.
The values of these settings are used to control various tracer features.
This section lists the settings that affect attribute collection and reporting.
This section lists the remaining newrelic.ini settings.
If you need more help, check out these support and learning resources:
- Suggest a change and learn how to contribute to our PHP agent open source repository.
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.