PHP per-directory INI settings

Most PHP agent configuration variables can be set on a per-directory basis. This option is often used when there is a single web server serving multiple applications, and you want to adjust settings (for example, the app name) on an application-by-application basis.

The process for setting per-directory values depends on the environment. This document describes the three most common environments:

Another option: API calls

If you are trying to change the name the application reports as, you can use the newrelic_set_appname() API call instead of per-directory settings. For other settings that you can modify with the API, see PHP agent API.

If you do not have access to the code for your application, or if you need to isolate your applications to their own virtual hosts for other reasons, then use the following per-directory settings to override any configuration file settings.

Apache per-directory settings for PHP

When using the PHP module, Apache provides two mechanisms for setting PHP variables outside the INI file:

Edit the httpd.conf file or one of the files it includes.

Use the syntax from the INI file examples when your web server serves up multiple domains. To view each of these domains separately in the New Relic UI:

For your main domain, set newrelic.appname = "My Main Domain" in your global INI file.

Override the value for each of the virtual hosts by adding php_value entries as part of your virtual host configuration.

Ensure you use the proper module name for your PHP install. Replace PHP_MODULE in the examples below with the name of the installed PHP5 module. This name depends on the Linux and/or PHP distribution being used. For example, common names include php5_module, mod_php5, php_module, etc. Capitalization may vary.

For Apache servers, you can find the module names in one of the following ways. Each will generate a list of installed modules.

From the command line, run:

apachectl -t -D DUMP_MODULES

OR

From within a webpage, use:

<?php
print_r(apache_get_modules()):
?>

Setting appname by domain

Here is an example of separating domains, where PHP_MODULE is the name of your PHP5 module.

PHP-FPM per-directory settings

The FastCGI Process Manager (PHP-FPM) is dedicated to PHP. It spawns a number of worker processes that wait for requests. It increases performance by not re-initializing the PHP engine on each invocation, allowing each process to deal with a number of requests before it recycles.

When using PHP-FPM, there are two mechanisms for setting PHP variables outside the INI file and one special technique for NGINX:

Edit the PHP-FPM pool per-directory settings

Changing variables on a per-directory basis can be more difficult if you use PHP-FPM. You must use multiple PHP-FPM pools, one for each virtual host or unique application.

A pool is a dedicated set of worker children that will only serve requests for that pool. Because it requires dedicated worker children, PHP-FPM scales poorly if you have a large number of virtual hosts or applications for which you want to set individual options.

To configure PHP-FPM on a per-directory basis:

Set the main application name in the INI file.

Set up two pools for the two additional applications.

Override the application name setting in those pools.

Each pool has to have a unique connection mechanism (so you can identify which pool to use in your web server configuration file). Here is an example of php-fpm.conf:

The general format of the per-pool variable settings is php_value[name] = VALUE for string or numeric variables, or php_flag[name] = VALUE for boolean values. Always surround string values with quote marks ". Boolean values must be either on or off.

Once the configuration file is set up, the web server must be instructed to use the different pools for different parts of the website. For more information, refer to the documentation for your web server.

Create a .user.ini file.

You can use the syntax from the INI file example for CGI/FastCGI in a .user.ini file. This is similar to a .htaccess file for Apache but is unique to PHP-FPM. The directory that PHP is executed in is scanned for a .user.ini file. More information about this feature is available in the PHP user.ini files documentation.

Change the name of the app using the following steps In the root directory of the web page.

Create the .user.ini file

Add the setting you wish to changenewrelic.appname = "New Appname"

Save the file.

By default, the .user.ini file is read every five minutes so no restart is necessary

This is useful in the following scenarios:

The server config doesn't work. In NGINX/PHP-FPM setup, there can be a lack of communication between FastCGI and PHP and the information fromfastcgi_param PHP_VALUE newrelic.appname="Appname"
never reaches PHP.

The .htaccess doesn't work, such as where PHP is implemented with suPHP

Edit the NGINX config file.

This section applies only to PHP 5.3.3 or higher.

Here is a small fragment of an NGINX config file showing the general procedure to pass values to your FastCGI manager based on an NGINX location.

Roll-up application names

If you want to have an overall view of how the server is performing across all virtual hosts or all applications, it is convenient to be able to report to more than one application at a time. For example, report to a virtual host specific application as well as a roll-up application.

To do this, set more than one application name for the newrelic.appname parameter by separating each application name with a semicolon. The primary application name is first, and the secondary application names next. You can define up to two extra application names.

For example:

newrelic.appname="Virtual Host 1;All Virtual Hosts"

This will report to two New Relic applications: "Virtual Host 1" and "All Virtual Hosts". Note: This feature is only available in versions 2.4 or higher of the PHP agent.