PHP Manual Instrumentation
Datadog's Research Report: The State of Serverless Report: The State of Serverless

PHP Manual Instrumentation

Even if Datadog does not officially support your web framework, you may not need to perform any manual instrumentation. See automatic instrumentation for more details.

If you really need manual instrumentation, e.g., because you want to trace specific custom methods in your application, first install the PHP tracer dependency with Composer:

composer require datadog/dd-trace

Trace a custom function or method

The dd_trace() function hooks into existing functions and methods to:

  • Open a span before the code executes
  • Set additional tags or errors on the span
  • Close the span when it is done
  • Modify the arguments or the return value

For example, the following snippet traces the CustomDriver::doWork() method, adds custom tags, reports any exceptions as errors on the span, and then re-throws the exceptions.

<?php
  dd_trace("CustomDriver", "doWork", function (...$args) {
      // Start a new span
      $scope = \DDTrace\GlobalTracer::get()->startActiveSpan('CustomDriver.doWork');
      $span = $scope->getSpan();

      // Access object members via $this
      $span->setTag(\DDTrace\Tag::RESOURCE_NAME, $this->workToDo);

      try {
          // Execute the original method. Note: dd_trace_forward_call() - handles any parameters automatically
          $result = dd_trace_forward_call();
          // Set a tag based on the return value
          $span->setTag('doWork.size', count($result));
          return $result;
      } catch (Exception $e) {
          // Inform the tracer that there was an exception thrown
          $span->setError($e);
          // Bubble up the exception
          throw $e;
      } finally {
          // Close the span
          $span->finish();
      }
  });
?>

The root span an be accessed later on directly from the global tracer via Tracer::getRootScope(). This is useful in contexts where the metadata to be added to the root span does not exist in early script execution.

<?php
  $rootSpan = \DDTrace\GlobalTracer::get()
      ->getRootScope()
      ->getSpan();
  $rootSpan->setTag(\DDTrace\Tag::HTTP_STATUS_CODE, 200);
?>

Zend Framework 1 manual instrumentation

Zend Framework 1 is automatically instrumented by default, so you are not required to modify your ZF1 project. However, if automatic instrumentation is disabled, enable the tracer manually.

First, download the latest source code from the releases page. Extract the zip file and copy the src/DDTrace folder to your application’s /library folder. Then add the following to your application/configs/application.ini file:

autoloaderNamespaces[] = "DDTrace_"
pluginPaths.DDTrace = APPLICATION_PATH "/../library/DDTrace/Integrations/ZendFramework/V1"
resources.ddtrace = true

PHP code optimization

Prior to PHP 7, some frameworks provided ways to compile PHP classes—e.g., through the Laravel’s php artisan optimize command.

While this has been deprecated if you are using PHP 7.x, you still may use this caching mechanism in your app prior to version 7.x. In this case, Datadog suggests you use the OpenTracing API instead of adding datadog/dd-trace to your Composer file.

Further Reading