README

Experimental PHP Tracer!

This project is experimental and under active development. Use it at your own risk.

Installation

composer require datadog/dd-trace

Requirements

• PHP 5.6 or later

Usage

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

Using the tracer

To start using the DataDog Tracer with the OpenTracing API, you should first initialize the tracer:

use DDTrace\Tracer;
use OpenTracing\GlobalTracer;

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

// Sets a global tracer (singleton). Ideally tracer should be
// injected as a dependency
GlobalTracer::set($tracer);

$application->run();

// Flushes traces to agent.
register_shutdown_function(function() {
    GlobalTracer::get()->flush();
});

PHP as a request scoped language has no simple means to pass the collected spans data to a background process without blocking the main request thread/process. It is mandatory to execute the Tracer::flush() after the response is served to the client by using register_shutdown_function.

Advanced configuration

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
    ]
);

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

• Starting a root span
• Starting a span for a given request
• Active span and scope manager
  • Creating a child span assigning parent manually
  • Creating a child span using automatic active span management
• Using span options

Propagation of context

• Serializing context to the wire
• Deserializing context from the wire
• Propagation formats

Contributing

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

Run tests

composer test

Fix lint

composer fix-lint

Releasing

See RELEASING for more information on releasing new versions.