PHP Tracer
This is Beta software. We do not recommend using it in production yet.
For a basic product overview, check out our setup documentation.
For installation, configuration, and and details about using the API, check out our API documentation.
For descriptions of terminology used in APM, take a look at the official documentation.
composer require datadog/dd-trace
- PHP 7.0 or later
In order to be familiar with tracing elements it is recommended to read the OpenTracing specification.
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
.
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
);
- Starting a root span
- Starting a span for a given request
- Active span and scope manager
- Using span options
Before contributing to this open source project, read our CONTRIBUTING.md.
The recommended way to run tests is using the preconfigured docker images that we provide for the different PHP versions.
- PHP 5.6:
datadog/docker-library:ddtrace_php_5_6
- PHP 7.0:
datadog/docker-library:ddtrace_php_7_0
- PHP 7.1:
datadog/docker-library:ddtrace_php_7_1
- PHP 7.2:
datadog/docker-library:ddtrace_php_7_2
In order to run tests open a bash
in the proper image, e.g. for PHP 5.6;
$ docker-compose run 5.6 bash
At the begin of you session, or at any time when you update the php extension, install it:
$ composer install-ext
In order to run the tracer tests:
$ composer test
Please note that the later is a wrapper around phpunit
, so you can use all the common
options that you would with phpunit
. Note, though,
that you need prepend the options list with the additional --
dashes that composer
requires:
# Run a suite and a filter
$ composer test -- --testsuite=unit --filter=Predis
In order to run tests for the php extension:
$ composer test-ext
composer fix-lint
See RELEASING for more information on releasing new versions.