• EnglishEspañol日本語한국어Português
  • 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.

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.

Log fowarding

If you're using a supported logging framework, you can direct the agent to forward your app logs to New Relic.

  • newrelic.application_logging.forward.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

Log context data

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


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:

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:


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.

Custom events

This section lists the settings that affect custom event reporting.

Code-level metrics

This section lists the settings that affect the reporting of code-level metrics.

Errors inbox configuration

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.

Other .ini settings

This section lists the remaining newrelic.ini settings.

Copyright © 2024 New Relic Inc.

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