New Relic for PHP FAQs

This document provides answers to some of the most frequently asked questions about New Relic's PHP agent.

  1. What is the recommended environment for the agent?
  2. I am having trouble - what can I provide support for the quickest solution?
  3. How do I report multiple applications or virtual hosts?
  4. Why are there two daemon processes?
  5. Why do I still see uninstrumented time with detail=1?
  6. Why do INI changes not take effect immediately?
  7. Is there a version of the agent for Windows?
  8. What does a protocol mismatch error in my log files mean?
  9. Do I need root (superuser) access to use New Relic?
  10. Why are all my transactions named index.php?

Newer is almost always better. This is especially true with both the PHP engine and Apache. Both projects are actively maintained, and both are the frequent target of security attacks. The development teams of both products are constantly releasing updates that fix security issues or improve performance and fix bugs. Therefore, New Relic strongly recommends that you use the latest possible version in the stable branch of each of these products.

For Apache, we recommend the latest version in the 2.4 stable series, or the 2.2 legacy series.

I am having trouble. What can I provide to Support for the quickest solution?

First, review New Relic's troubleshooting section to make sure that your issue isn't one of the more common ones with a known, quick solution. If that guide doesn't solve your issue, get support at support.newrelic.com.

Second, if the issue you are experiencing is repeatable, collect both agent and daemon logs at the verbosedebug log level. For most problems, this is key to quickly diagnosing the problem. Use the logfile to troubleshoot the issue. If you need further assistance, get support at support.newrelic.com.

  1. Save aside your current logs in /var/log/newrelic.
    cd /var/log/newrelic
    mv php_agent.log php_agent.log.old
    mv newrelic-daemon.log newrelic-daemon.log.old
    
  2. In /etc/newrelic/newrelic.cfg make sure you set loglevel=verbosedebug. If you are not using the newrelic.cfg file for configuring the daemon, set newrelic.daemon.loglevel = "verbosedebug" in your INI file.
  3. In your PHP INI file set newrelic.loglevel=verbosedebug.
  4. Restart your daemon. If you are using the external daemon mode use /etc/init.d/newrelic-daemon restart. If you are using the automatic mode please kill any copies of the daemon before restarting your web server.
  5. Restart your web server.
  6. Let your web server run for a few minutes, long enough to reproduce the problem you are experiencing.
  7. Zip php_agent.log, newrelic-daemon.log and your Apache error log and attach the Zip file (or compressed tar file) with your bug report.

How do I report multiple applications or virtual hosts?

Frequently one single web server is used for supporting more than one application or multiple virtual hosts, and you need to report all of those applications or hosts separately so that you can judge individual performance. You thus need to change the "application name" and possibly other parameters on a host by host, or directory by directory basis. Exactly how this is achieved depends entirely on your actual web infrastructure, and is covered in detail in per directory settings.. Please read that section carefully.

Why are there two daemon processes?

The New Relic daemon is a vital component of the PHP agent. It acts as a proxy between the various copies of PHP inside your web server and the New Relic data collectors. It is the only entity that communicates with New Relic. Therefore, it is absolutely vital that this process is always running, else no data will be sent to New Relic and you will see empty graphs. In order to maintain this stability, when the daemon first starts up it spawns a copy of itself. The original process becomes a "watcher" process, and does almost no work whatsoever. The second one is the "worker" process that does the real work. In the event of either a failure or a special instruction from the RPM servers to reset, the worker process will terminate. The watcher process sees that this is an unnatural shutdown of the worker and immediately respawns a new worker process, thus ensuring that there is the absolute minimum amount of downtime. Only when the daemon is shut down in an orderly manner will the watcher not respawn a new worker, and will itself terminate.

Why do I still see uninstrumented time with detail=1?

There are two reasons why you may still see red blocks of uninstrumented time in a transaction trace. The first is if you have a function that is called frequently that is very quick, and below the default 2ms threshold for the top 100 list. The second, and most common cause is when a function takes a long time to execute but is written in C and is either an internal function or a function provided by an external module. The most frequent culprits are functions that send large blocks of data or large files to users. If the user is on a slow connection even sending small files, for example small images, could take a long time due to simple network latency. Since no internal or C extension functions are instrumented, the PHP agent has no-one to "blame" the time spent on, and this shows up in a transaction trace as uninstrumented time.

Why do INI changes not take effect immediately?

When Apache first starts up and initializes PHP, all of the INI settings are read, and the global defaults for any missing settings are set. Apache then creates a pool of "worker" processes to deal with requests. These worker processes inherit the settings set during initialization. You have no way of knowing exactly which worker process will deal with a given request. When you make INI file changes, there may still be hundreds of worker processes left with the old settings, and the main Apache process itself (which will periodically kill existing and spawn new worker processes) also has the original INI settings. Thus, until you restart your Apache server, most changes to your INI files will go un-noticed. The only exception to this is if you use PHP's "per-directory" setting mechanism using .htaccess files. Such settings are rare. Therefore, after you have made changes to your INI settings, you need to restart your Apache (or whatever other product you use) web server.

Is there a version of the agent for Windows?

Not currently, no. However, it is not out of the question, it just hasn't been specifically planned for yet. If you are interested in a Windows port of the agent please contact technical support so that we can both gauge interest in such a port, and notify you if such a port becomes available.

What does a protocol mismatch error in my log files mean?

After upgrading your agent you may see errors in your daemon log file along the lines of protocol mismatch: A.B != X.Y. There is only one possible reason you will ever see this message: your agent and daemon are out of sync with each other. The daemon and the actual agent (the PHP extension) are a very tightly coupled pair, and the daemon will only accept connections and commands from an agent that matches it. Sometimes the upgrade process will fail to kill the old daemon correctly and you may still have old daemon processes running, but more frequently this error is caused by not restarting your web server after an upgrade. If the daemon was upgraded correctly but your web server still contains older agents, you will see this error. The error itself points to which is the culprit for being out of date. If the number A.B is less than the number X.Y, it means that you have an out of date agent trying to communicate with a more modern daemon. However if the number A.B is greater than the number X.Y then it means that your daemon is out of date, and the most likely cause is that you have too many daemons running. In this case, kill all of the currently running newrelic-daemon processes, and restart the daemon using /etc/init.d/newrelic-daemon start.

Do I need root (superuser) access to use New Relic?

The short answer is: no. Neither the New Relic daemon nor the agent require any form of elevated privileges. However, a lot depends on how you install the package. If you use the system level package manager such as yum or apt, then those tools themselves require root permissions in order to run. However once the package is installed, no elevated privileges are required, except that the daemon does need to run as a background process. Some system administrators do not allow un-privileged users to run such processes. If you are using a shared host service, your host provider may not allow such processes either. You will need to negotiate with your provider or system administrator to allow the daemon to run in the background.

You may also need elevated privileges in order to install a PHP extension module. Usually this is due to simple directory permission settings. The PHP agent (and in fact any PHP extension) is not required to be installed in the PHP extension directory. You can use the tar distributions, leave the extension module somewhere in your home directory, and simply use a full path to the extension in your INI file. For example, if your INI file contains the line extension=newrelic.so then the extension must be installed in your PHP extensions directory. However if you use a full path, for example extension=/home/johndoe/newrelic/newrelic.so then you do not need special permissions to install the agent. The only requirement is that the path specified is visible to the PHP engine when it initializes, which may have directory permissions implications. Please contact support if you are struggling with installing the extension.

Why are all my transactions named index.php?

This is a symptom of using a framework that we do not explicitly support. Most frameworks use some form of "Model-View-Controller" or MVC architecture. In such systems, all requests actually are made to a single file; either using URL parameters, POST data or some other mechanism, that file will determine what action needs to be taken. As a trivial example, you may see a URL such as http://foo.com/index.php?action=view&article=1234. Thus, although the URL looks like it is accessing index.php, internally that file will look at the parameters and route to view.php and deal with viewing the given article.

For frameworks that New Relic explicitly supports, we have code in the agent to "reach into" the framework code and determine a more appropriate transaction name automatically. In this case, we would call the transaction "view". If you are using a home-grown or closed source framework like vBulletin, we do not know how to name your transaction, and you will need to modify your framework yourself. You do this using the newrelic_name_transaction() API call at some suitable point in your code when you know the action that needs to be taken. Please be sure to read the article on metric grouping issues for information on how best to name transactions and common pitfalls to avoid.

For more help

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