Docs » µAPM Instrumentation Guide » PHP Instrumentation

PHP Instrumentation 🔗

Important

Before you start instrumenting your applications, review the information in Instrumentation Overview.

Adding tracing functionality to your PHP project, like in other platforms, generally consists of incorporating the initialization of a global tracer and using its interfaces for the creation and modification of spans to denote the runtime state of your application. For web applications implementing dozens of routes and using middleware that generates complex database queries, manual instrumentation can become burdensome. This is especially true for cross-team deployments, where service owners and instrumentors don’t share memberships, or when legacy components are currently without SMEs. Fortunately, there is a helpful library for auto-instrumenting your applications: SignalFx Tracing for PHP.

The SignalFx Tracing library for PHP is an extension that automatically wraps supported library and framework functionality with its traced equivalent. The utility can be installed via your system package manager after downloading the latest release:

# Using dpkg:
$ dpkg -i signalfx-tracing.deb

# Using rpm:
$ rpm -ivh signalfx-tracing.rpm

# Using apk:
$ apk add signalfx-tracing.apk --allow-untrusted

# Directly from the release bundle:
$ tar -xf signalfx-tracing.tar.gz -C / && /opt/signalfx-php-tracing/bin/post-install.sh

Auto-instrumentation 🔗

Note

PHP auto-instrumentation is currently in beta.

In many environments, no configuration or code changes will be necessary for supported libraries and frameworks to become automatically instrumented and for a tracer to report their activity to SignalFx in real time. To establish distributed traces over the remote request-response points of your application, we automatically configure the B3 span context propagation codec for HTTP clients and supported web frameworks. For web environments using a currently unsupported framework, a root span will still be created for each fielded request using the PHP standard library’s server execution environment.

PHP versions 5.4 running the Zend Engine are supported. Currently the following libraries are provided with auto-instrumentation:

Library Supported Versions
CakePHP (beta) 2.x
Curl All supported PHP versions
Elasticsearch (beta) 1.x
Eloquent (beta) All supported Laravel versions
Guzzle (beta) 5.0+
Laravel 4.2, 5.0+
Lumen (beta) 5.2+
Memcached (beta) All supported PHP versions
MongoDB (beta) 1.4
MySQLi (beta) All supported PHP versions
PDO All supported PHP versions
Predis (beta) 1.1
Slim (beta) 3.x
Symfony (beta) 3.3, 3.4, 4.x
Zend (beta) 1.12

Custom instrumentation 🔗

We are aware that your applications are not just client and framework scaffolding. You are the best judge of the meaning and value behind the procedures initiated by your users. In situations where you desire more powerful, introspective performance-monitoring capabilities, you are able to build upon the provided instrumentations by modifying and adding to the traces automatically generated throughout your applications. The SignalFx Tracing library for PHP provides an OpenTracing-compatible tracer for you to annotate the execution of your business logic for providing the greatest possible value to your trace data.

use SignalFx\GlobalTracer;
use OpenTracing\Tags;

function myApplicationLogic($indicator) {
  $tracer = GlobalTracer::get(); //  Provides the tracer used by signalfx_tracing instrumentations
  $span = $tracer->startActiveSpan('myApplicationLogic')->getSpan();
  $span->setTag('indicator', $indicator);

  try {
    $widget = myAdditionalApplicationLogic($indicator);
    $span->setTag('widget', $widget);
    return $widget;
  } catch (Exception $e) {
    $span->setTag(Tags\ERROR, true)
    throw $e;
  } finally {
    $span->finish();
  }
}

For advanced configuration and usage instructions, please see the utility’s documentation.