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 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.
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 in per directory settings.. 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 using
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
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
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
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
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.
if your INI file contains the line
then the extension must be installed in your PHP extensions directory.
However if you use a full path,
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.
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 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
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.
If you need additional help, get support at support.newrelic.com.