• Log inStart now

PHP agent configuration

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.

Configuration order of precedence

Here is a simple illustration of the order of precedence that the PHP agent follows for configuration. Server-side configuration is not applicable. The only values you can change in the UI for apps using the PHP agent are the app's alias and its Apdex-T value.

With New Relic's PHP agent, API settings override per-directory configuration settings. Per-directory settings override the php.ini file settings. Server-side configuration is not applicable.

Configuration file variables

During installation, the newrelic-install script provides information about the configuration files it created or a list of files you need to edit. By default it will attempt to create a configuration file named newrelic.ini.

In some cases, you may be instructed to add configuration options to your php.ini file. Only do this if necessary. Exactly which file you need to edit depends on how your particular version (or versions) of PHP were configured.

The two most common configurations are:

  • Use a single newrelic.ini file. This is usually the default if you have installed or compiled PHP yourself with no special options.
  • Scan a given directory for all .ini files.

If you are unsure which file to edit:

  • From the command line, review the output of php -i.

  • In a browser, review the output of a page containing the script:

    <?php phpinfo(); ?>
  • If the newrelic.ini file appears, use it.

Variable scope

Each variable for your newrelic.ini file has a defined scope. The scope controls where the setting can be established or modified.

The two scopes supported for New Relic settings are:

  • SYSTEM: Values set globally in the global newrelic.ini file.
  • PERDIR: Values set on a per-directory basis.

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

Can be set for:



Set in the global newrelic.ini file.

Set on a per-directory basis.


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 values can contain any alphanumeric character and punctuation. The value is delimited by quotes.


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.


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.

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

If you're using New Relic CodeStream to monitor performance from your IDE you may also want to associate repositories with your services and associate build SHAs or release tags with errors.

Daemon .ini settings

The values of these settings control the daemon startup. When the agent detects that the daemon needs to be started, it will convert these options into the appropriate command line options for the daemon.

All of these settings mirror the settings in the newrelic.cfg file. They are repeated here to keep all of the .ini settings in one place. Each setting in newrelic.cfg has its counterpart here, with newrelic.daemon. as the prefix. For example, the ssl setting in newrelic.cfg is newrelic.daemon.ssl in an .ini file.


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 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 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.cfg startup mechanism for the daemon, this setting and the address setting 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 "ns", "us", "ms", "s", "m" and "h".

The specified timeout value will be passed to the daemon via the --wait-for-port flag. This causes daemon startup to block until a socket is acquired or until the timeout is elapsed.

Recommendation: If setting a timeout, the recommended value is 2s to 5s. It is recommended to only set this timeout when instrumenting long-lived background tasks, as in case of daemon start problems the agent will block for the given timeout at every transaction start.

Logs in context

Starting with the PHP agent 10.1.0 release, support for logs in context has been added directly to the agent, making it easy to use for supported logging frameworks.

Changing these settings in your local agent configuration file (newrelic.ini) requires a restart of the webserver for them to take effect.


Always restart your web server after changing INI settings. Otherwise, they may not take effect immediately.

An example configuration that enabled logs in context with logging metrics and agent log forwarding would be:

newrelic.application_logging.enabled = true
newrelic.application_logging.metrics.enabled = true
newrelic.application_logging.forwarding.enabled = true

The value newrelic.application_logging.enabled controls if the logs in context feature is active or not.

If you're using a supported logging framework and want to use the agent to send your application logs to New Relic, you can control that through settings newrelic.config.application_logging.forwarding prefixed INI settings. Options available are:

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:


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.

Other tracer .ini settings

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

Attribute settings

This section lists the settings that affect attribute collection and reporting.

Other .ini settings

This section lists the remaining newrelic.ini settings.

Copyright © 2022 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.