PHP per-directory INI settings

Most of the configuration variables can be set on a per-directory basis (see PHP agent settings). This can be used when you have a single web server that is serving multiple applications, and:

• You want to use a different application name for each of those applications.
• You want to adjust certain settings on an application by application basis.

The mechanism to set per-directory values depends on the environment. This describes the three most common environments: Apache, php-fpm, and nginx.

Contents

• Using API calls
• Apache settings for PHP
• INI file per-directory configuration
• .htaccess per-directory configuration
• php-fpm per-directory configuration
• nginx per-directory configuration
• Roll-up application names
• For more help

Using API calls

Recommendation: Change your application name on a per-directory basis. This is useful when serving multiple applications from a single web server. While you can use per-directory settings to accomplish this, you can also use the newrelic_set_appname() API call. For other settings that you can modify, see The PHP API. Be sure to assign a unique name to each application.

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 follow the instructions to override the configuration file settings for your virtual hosts.

Apache settings for PHP

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

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

INI file per-directory configuration

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

1. For your main domain, set newrelic.appname = "My Main Domain" in your global INI file.
2. Override that value for each of the virtual hosts by adding php_value entries as part of your virtual host configuration.

Note: 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 two ways. Each will generate a list of installed modules.

1. From the command line, run apachectl -t -D DUMP_MODULES.
   OR
2. From within a webpage, use this:
   print_r(apache_get_modules()):
?>

Here is an example of separating domains.

Note: Replace PHP_MODULE if you use this example.

  ServerName www.myvhost1.com
  DocumentRoot "/path/to/vhost1/"
  ...
  
    php_value newrelic.appname "Virtual Host 1"
  



  ServerName www.myvhost2.com
  DocumentRoot "/path/to/vhost2/"
  ...
  
    php_value newrelic.appname "Virtual Host 2"
  

In the above example, the newrelic.appname is set to a different value for each virtual host. For string and number values, use php_value name VALUE, where:

• name is the name of the INI setting to modify as listed in the PHP INI settings.
• VALUE is the value you want to set to for that particular virtual host.

Be sure to surround string values in quotes ("").

If you want to change a boolean setting, use the syntax php_flag name VALUE, where name is the variable name as listed in the PHP INI settings, and VALUE is either on or off.

To disable the New Relic agent completely for a virtual host, use a boolean flag:

  ServerName www.myvhost3.com
  DocumentRoot "/path/to/vhost3/"
  ...
  
    php_flag newrelic.enabled off
  

.htaccess per-directory configuration

You can also use the syntax from the INI file example inside an .htaccess file. For example:

php_value newrelic.appname "My Blog App"

This allows you to control settings on a per-directory basis from within the directories.

In this example, your web server has its document root at /data/webroot. You also have two sub-directories for specialized applications:

• Your /data/webroot/blog contains a blog application.
• Your /data/webroot/shop contains a shopping cart application.

To have all three portions of your site reported as distinct applications in the New Relic UI, do this:

1. Set the name of your main application in your INI file.
2. Override that name using an .htaccess file in each of the specialized directories.

Any part of your web server (for example, /data/webroot/something) that does not have a specific.htaccess file will use the global application name defined in the INI file.

Note: The .htaccess file must be in the top-level directory for that application. Objects in that directory, or its subdirectories, will use the value specified in the .htaccess file.

For more information about using and securing .htaccess files, see the Apache HTTP server tutorial  .

php-fpm per-directory configuration

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.

For more information on php-fpm, see php-fpm's about page  and FastCGI Process Manager on php.net  .

Note: 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:

1. Set the main application name in the INI file.
2. Set up two pools for the two additional applications.
3. 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:

[app1]
listen=/tmp/pool-app1.sock
php_value[newrelic.appname] = "My App 1"

[app2]
listen=/tmp/pool-app2.sock
php_value[newrelic.appname] = "My App 2"

[app3]
listen=/tmp/pool-app3.sock
php_flag[newrelic.enabled] = off

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 quotes (""). 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.

nginx per-directory configuration

Note: This section applies only to PHP 5.3.3 or later.

Here is a small fragment of an nginx config file (similar to the Apache example) that shows the general procedure to pass values to your FastCGI manager based on an nginx location.

location /blog {
  fastcgi_param PHP_VALUE "newrelic.appname=My Blog";
  ...
}

location /shop {
  fastcgi_param PHP_VALUE "newrelic.appname=Shopping Cart";
  ...
}

location /admin{
  fastcgi_param PHP_VALUE "newrelic.enabled=false";
  ...
}
 

Recommendation: A better approach for nginx may be to use API calls. The following code snippet (for PHP agent 2.7 and higher) is an example.

  if (extension_loaded ('newrelic')) {
    newrelic_set_appname ("My App 1");
  }

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 version 2.4 and later of the PHP agent.

For more help

Additional documentation resources include:

• New Relic for PHP (compatibility and requirements, license key information)
• PHP agent (newrelic.ini) settings (configuration settings for the PHP agent)
• Proxy daemon (newrelic.cfg) settings (configuration settings for the PHP proxy daemon)

If you need additional help, get support at support.newrelic.com  .

https://docs.newrelic.com/docs/agents/php-agent/configuration/php-directory-ini-settings