• EnglishEspañol日本語한국어Português
  • Log inStart now

Distributed tracing for your PHP services

Distributed tracing allows you to see the entire journey of your requests throughout a distributed system. The PHP agent automatically instruments with distributed tracing a number of native PHP functions, as well as some third party HTTP clients:

For the PHP agent, we offer two types of distributed tracing (for more details, see How span sampling works):

  • Standard (head-based sampling): Before any traces arrive, we determine a set percentage of traces to accept and analyze. This gives you a solid starting point to see how tracing can help you. It is turned on by default in PHP agents 9.21.0 and higher.

  • Infinite Tracing (tail-based sampling): Our cloud-based service accepts all your traces and then sorts through them to find the most important. After you set up standard tracing, we recommend you add this option because it analyzes all of your traces and gives you configuration options to sample the traces that matter most to you.

All the steps you need to get started with distributed tracing are right here:

New PHP agents

Whether you just want to try out standard distributed tracing (head-based sampling) or also want to set up Infinite Tracing (tail-based sampling), you need to start by setting up standard tracing. We'll get you through the APM agent installation to get head-based sampling going. After that, you can set up Infinite Tracing, which is optional but recommended.

Install an agent to get standard distributed tracing

This is the best approach to set up standard distributed tracing if you haven't installed any APM agents for your services yet, or if you want to instrument additional services.

If you already have some services instrumented with this APM agent, and you want to include them in distributed tracing, you'll need to manually enable distributed tracing for each service. See Options for older PHP agents.


You'll need a New Relic account to set up distributed tracing. If you don't already have one, you can quickly create a free account.

Step 1. Identify services

Figure out which services touch your request so you can instrument each of them to send trace data to New Relic.

Step 2. Instrument each service with an APM agent

You'll repeat the agent installation routine for each service involved in your transactions. If some of your services use other languages, simply repeat the installation steps for those languages.

To start the installation routine, click the tile below. When you are finished installing each agent, return here to see tips for viewing your traces.

Start installation

Step 3. View traces

After you instrument each of your services with APM agents, generate some traffic in your application so we can capture some traces. Here are some ways to view your traces in the UI:

For more help finding your traces in the UI:

Set up Infinite Tracing

Standard distributed tracing for APM agents (above) captures up to 10% of your traces, but if you want us to analyze all your data and find the most relevant traces, you can set up Infinite Tracing.


To learn more about this feature, see Infinite Tracing.

Before beginning, first ensure you meet the requirements.

Step 1. Complete the new agent installation

The Infinite Tracing setup builds on the instrumentation step from the new agent installation for standard distributed tracing. After you finish installing the agents, continue with the trace observer setup.

Step 2. Set up the trace observer

The trace observer is a New Relic AWS-based service that collects and analyzes all your traces. Follow the instructions in Set up trace observer. When you're done, return here with your trace observer information and continue with the next step to configure the agent.

Step 3: Configure the agent for Infinite Tracing

Infinite Tracing configuration settings include the standard distributed tracing plus information about the trace observer. Note that server-side configuration is not available for Infinite Tracing.


If you need help with proxy configuration, see Proxy support.

Step 4. (Optional) Customize Infinite Tracing

After you add the agent configuration settings, you should start seeing data in the New Relic UI. After you spend some time analyzing your data, you may want to adjust some of the features of Infinite Tracing:

Options for older PHP agents

If you have older PHP agents, confirm the distributed tracing features you want are supported before enabling it.

Compatibility guide

After reviewing the compatibility information below, see Configure your older PHP agents.

Configure your older PHP agents

See the settings below to enable distributed tracing.


If you've been using an older agent without distributed tracing, before turning on distributed tracing, check out Impacts to APM.

Set trace detail level

Distributed tracing support depends on the PHP agent's transaction tracer. When distributed tracing is enabled, a span is created for each segment seen by the transaction tracer.

As spans are sampled, the PHP agent will prioritize spans related to external calls above other spans, which are then recorded in descending order of their duration.

If you find that there are too many unimportant spans being reported for PHP function calls, you can reduce the detail of the transaction tracer by setting newrelic.transaction_tracer.detail to 0. You may then use the newrelic.transaction_tracer.custom configuration setting or the newrelic_add_custom_tracer API method to add trace segments and spans for the specific PHP function or methods you want to add to your traces.


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 spans. To get spans related to PHP function calls, update to version 9.0 or higher.

Manually instrument applications and services with PHP agent API


W3C Trace Context support was added in version 9.8. With this, the API for manually instrumenting applications has changed from the JSON payload related functions:


To the header array forms:


The JSON functions are now considered deprecated, and will be removed in a future release.

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:

  1. Modify your service or application to create or insert the distributed tracing data
  2. Modify your service or application to accept distributed trace data 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 or insert headers, you're telling New Relic you want this request or transaction or request to participate in a distributed trace. When you accept them, 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 APIs.

Header API

Payload API (deprecated)

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.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.