• /
  • Log in

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.

Important

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.

php-config-order.png

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:

SYSTEM

PERDIR

Set in the global newrelic.ini file.

Set on a per-directory basis.

Important

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

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

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.

Important

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 5.2.0.141 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 9.2.0.247 or higher.

    Caution

    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.

    Important

    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.

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.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.