Datadog Tracing PHP Client (Beta)
Clone or download
labbati Bump version 0.9.1 (#231)
* Bump version 0.9.1

* Bump version 0.9.1 - followup

* Bump version 0.9.1 - followup
Latest commit 9a69308 Jan 11, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci do not parallelize the builds Jan 7, 2019
.composer Laravel pipelines tracer supporting configurable handler method. (#158) Nov 30, 2018
.github Fix GitHub PR template link Dec 3, 2018
dockerfiles Disable 7.0 verification build, and disable cache to ensure other ste… Jan 7, 2019
docs Add PECL config (#210) Jan 7, 2019
package Fix deprecated style of ini comments and avoid failing alpine builds … Dec 14, 2018
src Bump version 0.9.1 (#231) Jan 11, 2019
tests Make TryCatchFinally::execeuteAnyMethod use \Closure::bind Jan 11, 2019
.clang-format Disable eclint for c/c++ as it clashes with C specific Clang format o… Sep 27, 2018
.editorconfig Fix Dockerfile editorconfig and format dispatch.c Oct 26, 2018
.env.circleci .env.circleci fix ports Oct 23, 2018
.gitattributes Allow exporting files needed to build the extension Oct 15, 2018
.gitignore Allow testing of multiple library versions (#203) Jan 3, 2019
.phpcs.xml Move framework tests to tests root folder (#198) Dec 20, 2018
CHANGELOG.md Bump version 0.9.1 (#231) Jan 11, 2019
CONTRIBUTING.md Allow testing of multiple library versions (#203) Jan 3, 2019
DDMakefile Better docker-compose that includes building of debug php versions Nov 14, 2018
LICENSE Initial commit Feb 2, 2018
README.md Add PECL config (#210) Jan 7, 2019
RELEASING.md Adds more information to README. Mar 21, 2018
composer.json [tests] Downgrade phpunit to 4.* to prepare for php 5.4 Jan 3, 2019
config.m4 Add clang-format to CI Oct 1, 2018
docker-compose.yml Allow testing of multiple library versions (#203) Jan 3, 2019
package.xml Bump version 0.9.1 (#231) Jan 11, 2019
phpstan.neon Skip static analysis of the integrations for now, there's too much ma… Oct 10, 2018
phpunit.xml Allow testing of multiple library versions (#203) Jan 3, 2019

README.md

DD Trace PHP

CircleCI OpenTracing Badge Minimum PHP Version License Packagist Version Total Downloads

PHP Tracer

This is Beta software. We do not recommend using it in production yet.

Getting Started

The Datadog PHP Tracer brings APM and distributed tracing to PHP.

Prerequisites

If you haven't already, sign up for a free Datadog account and download and install the Datadog agent.

Make sure that APM is enabled. The agent does not have APM enabled by default so make sure to enable it.

Installation

The PHP tracer is composed of a PHP extension and a Composer package. You'll need to install both in order to start tracing your PHP projects.

Composer installation

First we'll install the Composer package.

$ composer require datadog/dd-trace opentracing/opentracing:@dev

Note: Since the OpenTracing dependency is still in beta, adding the opentracing/opentracing:@dev argument to the composer require command will ensure the library is installed without changing your Composer minimum stability settings.

Installing the extension (from a package)

Next we'll install the ddtrace extension. The easiest way to install the extension is from PECL.

$ sudo pecl install datadog_trace-beta

If you don't have pecl installed, you can install the extension from a package download. First download the appropriate package from the releases page. Then install the package with one of the commands below.

# using RPM package (RHEL/Centos 6+, Fedora 20+)
$ rpm -ivh datadog-php-tracer.rpm

# using DEB package (Debian Jessie+ , Ubuntu 14.04+)
$ deb -i datadog-php-tracer.deb

# using APK package (Alpine)
$ apk add datadog-php-tracer.apk --allow-untrusted

# using tar.gz archive (Other distributions using libc6)
$ tar -xf datadog-php-tracer.tar.gz -C /
  /opt/datadog-php/bin/post-install.sh

Installing the extension (manually)

The extension can also be installed manually from source. First download the source code from the releases page. Then compile and install the extension with the commands below.

$ cd /path/to/dd-trace-php
$ phpize
$ ./configure --enable-ddtrace
$ make
$ sudo make install

Instrumentation

Once the ddtrace extension and Composer package is installed, you can start tracing your PHP project. There are a few framework instrumentations available out of the box.

Manual instrumentation

If you are using another framework or CMS that is not listed above, you can manually instrument the tracer by wrapping your application code with a root span from the tracer.

use DDTrace\Tracer;
use OpenTracing\GlobalTracer;
use DDTrace\Integrations\IntegrationsLoader;

// Creates a tracer with default transport and propagators
$tracer = new Tracer();

// Sets a global tracer (singleton)
GlobalTracer::set($tracer);
// Flushes traces to agent on script shutdown
register_shutdown_function(function() {
    GlobalTracer::get()->flush();
});

// Enable the built-in integrations
IntegrationsLoader::load();

// Start a root span
$span = $tracer->startSpan('my_base_trace');

// Run your application here
// $myApplication->run();

// Close the root span after the application code has finished
$span->finish();

Notice we didn't specify an API key or any web endpoints. That's because the API key is set at the agent layer, so the PHP code just needs to know the hostname and port of the agent to send traces to Datadog. By default the PHP tracer will assume the agent hostname is localhost and the port is 8126. If you need to change these values, check out the configuration documentation.

Viewing the trace

Assuming the agent is running with APM enabled and it is configured with our API key, and assuming we successfully installed the ddtrace extension and the datadog/dd-trace package with Composer, we should be able to head over to the APM UI to see our trace.

Note: It might take a few minutes before your trace appears in the UI. Just refresh the page a few times until you see the screen change.

Digging deeper

For more information about configuration and specific framework integrations, check out the getting started docs.

Advanced configuration

In order to be familiar with tracing elements it is recommended to read the OpenTracing specification.

The transport can be customized by the config parameters:

use DDTrace\Encoders\Json;
use DDTrace\Transport\Http;

$transport = new Http(
    new Json(),
    $logger,
    [
        'endpoint' => 'http://localhost:8126/v0.3/traces', // Agent endpoint
    ]
);

The tracer can be customized by the config settings:

use DDTrace\Tracer;
use OpenTracing\Formats;

// Config for tracer
$config = [
    'service_name' => 'my_service', // The name of the service.
    'enabled' => true, // If tracer is not enabled, all spans will be created as noop.
    'global_tags' => ['host' => 'hostname'], // Set of tags being added to every span.
];

$tracer = new Tracer(
    $transport,
    [ Formats\TEXT_MAP => $textMap ],
    $config
);

Creating Spans

Propagation of context

Contributing

Before contributing to this open source project, read our CONTRIBUTING.md.

Releasing

See RELEASING for more information on releasing new versions.

Security Vulnerabilities

If you have found a security issue, please contact the security team directly at security@datadoghq.com.