NewRelic Integration With Dockerized Laravel/Lumen

We recently built an application using the Lumen framework as a dockerized application and deployed it on a Kubernetes cluster (AWS EKS).

We wanted to monitor the application using NewRelic APM as it helps you to analyze, troubleshoot and optimize applications easily.

As we started to do this, we find out that integrating NewRelic APM with PHP containers and running on Kubernetes, the setup is not so easy.
NewRelic has some instructions on their website but not so friendly.

After some struggle, we got it working and I decided to list the steps here if anyone needs it.

There are two components you will need for a working setup:

1. APM Daemon
   Official daemon docker image is available on the docker hub which you can use directly or extend it for your needs:
   https://hub.docker.com/r/newrelic/php-daemon
   In the case of Kubernetes, the daemon container is recommended to run as a daemonset.
2. APM agent
   APM agent you need to install in your PHP container as a PHP extension. Here are the straight forward instructions you can put in your Dockerfile.

Here is the sample docker-compose.yml file.
The php service builds image from above Dockerfile.

As you can see, there are four arguments variables you need to provide values for. These values would be inserted in newrelic.ini file that PHP will read when starting.

1. NEW_RELIC_AGENT_VERSION
   Make sure you get the latest version from https://download.newrelic.com/php_agent/archive/
2. NEW_RELIC_LICENSE_KEY
   This you can get from your NewRelic account
3. NEW_RELIC_APPNAME
   This is your application name which you would like to appear in the NewRelic Application list.
4. NEW_RELIC_DAEMON_ADDRESS
   This should be your daemon service name and port (default daemon port is 31339).
   e.g. newrelic-apm-daemon:31339

You should see the application listed in NewRelic dashboard if everything is set up properly. It can take around 5 mins to see your data in NewRelic.

Another way to ensure the data is sent to NewRelic, you can check agent container logs and daemon container logs.

These steps could be used for any PHP application and not just Laravel / Lumen.

Useful References:

1. https://docs.newrelic.com/docs/agents/php-agent/advanced-installation/docker-other-container-environments-install-php-agent#install-diff-containers
2. Sample docker-compose application:
   https://discuss.newrelic.com/t/relic-solution-php-agent-and-daemon-containers/84841

Laravel / Lumen Specific Settings:

• Sending Exceptions to NewRelic:
  Laravel overrides PHP’s default error handler. So, no exceptions/errors data is sent to NewRelic.
  To work around this problem the easiest way is to capture and send exception data in report() helper function in app/Exceptions/Handler.php.

if (extension_loaded('newrelic')) { 
   newrelic_notice_error(null, $exception); 
}

• Naming transactions in NewRelic as route names:
  You can get route details from Request object:

$route = $request->route();
if (isset($route[1]) && isset($route[1]['uses'])) {
   $transactionName = $route[1]['uses'];
}
if (extension_loaded('newrelic')) {
   newrelic_name_transaction($transactionName);
}

• Sending custom attributes for a NewRelic transaction:
  There are a lot of uses and one of them is tracing back errors.
  For example, a unique request-id could be sent as a custom attribute and it would show up in exception details. You can quickly check audit logs with the request-id to see other post parameters sent in the request.

if (extension_loaded('newrelic') && $requestId) {
   newrelic_add_custom_parameter('requestId', $requestId);
}