Distributed tracing for the PHP agent

New Relic APM's PHP agent supports distributed tracing, which lets you see the path that requests take as they travel through a distributed system. This document contains PHP-specific tips to enable distributed tracing for a PHP application or service.

For PHP agent versions 8.4 to 8.7: When distributed tracing is enabled, these versions behave as if newrelic.transaction_tracer.detail is set to 0 (as described above), which results in PHP function calls not generating span events. To get span events related to PHP function calls, update to version 9.0 or higher.

Manually instrument applications and services

If you're using an unsupported library, or have a non-HTTP based distributed system component (such as messaging queues), you can use the PHP agent API to manually identify transactions to be included in a distributed trace. This is a two step process:

Modify your service or application to create a distributed trace payload.

Modify your service or application to accept distributed trace payloads created by other transactions or requests.

The following example uses a generic message/job queue. While the actual details will vary depending on what sort of system you're trying to add to a distributed trace, the core concepts are the same. Also, while we've used a job queue as an example, you can use these methods with any distributed system component.

When you create a payload, you're telling New Relic you want this request or transaction or request to participate in a distributed trace. When you accept a payload, you're linking the current request or transaction with its parent request or transaction.

For more information about using manual instrumentation to get more detail or to see connections between services, see the documentation about distributed tracing payload APIs.

Create a distributed trace payload

Somewhere in your application you'll have code that looks or acts like the following:

// create a job object
$job = new \Generic\Queue\Job;
// set the information needed to run the queue job
$job->setData('info', $info);
// save the job
$job->save();

If you want this job to appear in a distributed trace, you need to create a distributed trace payload using newrelic_create_distributed_trace_payload, and then add that payload to the job's data:

If you need to transport the payload via a mechanism that requires HTTP safe strings, (HTTP headers, URL query strings, POST fields, etc.), the API includes distributed tracing methods and functions that will create and accept HTTP safe versions of the strings.

Command line PHP programs

PHP programs run from the PHP command line are always sampled by the agent's distributed tracer. Depending on the programs you run, these processes could see an over-representation in your collection of distributed traces. In these situations, you can opt to disable command line instrumentation by using the per-directory newrelic.enabled setting in your newrelic.ini files.