This document provides answers to some of the most frequently asked questions about New Relic's PHP agent.
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.
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 get you up and running, when you contact Technical Support it helps if you either log the bug with the same email address you used for creating your New Relic account, or that you include a link to the overview of the application that is giving you trouble. This helps us track down your account quicker. Also refer to Finding help.
Second, if the issue you are experiencing is repeatable, provide both agent and daemon logs at the
log level. For most problems, this is one of the first things the Support engineers will ask for, so if you provide the logs with the
original support query, it makes it possible to get back to you with an answer
or other steps to try even quicker. Here's how to prepare the most useful logs
cd /var/log/newrelic mv php_agent.log php_agent.log.old mv newrelic-daemon.log newrelic-daemon.log.old
/etc/newrelic/newrelic.cfgmake sure you set
loglevel=verbosedebug. If you are not using the
newrelic.cfgfile for configuring the daemon, set
newrelic.daemon.loglevel = "verbosedebug"in your INI file.
/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.
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 over here.. Please read that section carefully.
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.
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.
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
.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.
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.
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
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
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,
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.
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
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
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
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
If you still have problems, submit a support ticket (for fastest service) or email support @ New Relic. Also, you may be able to find support from the community at Stack Overflow. Tag your post with