PHP agent release notesRSS

New features in 9.0

Detailed transaction traces now available when distributed tracing is enabled.

This release includes a refactor of segment storage to allow the agent to sort and apply different prioritization of segments that are used for transaction traces instead of distributed tracing. The PHP agent 8.4 release included limited support for distributed tracing, which resulted in the loss of detailed transaction traces for individual PHP services when distributed tracing was enabled.

The refactor in this new release allows the agent to send up the segments (spans) you want to view for a distributed trace that includes PHP services. It also separately provides as much segment detail as possible when exploring transaction traces for an individual PHP service.

Notes:

• The instructions to enable distributed tracing have not changed with this release.
• The behavior of newrelic.transaction_tracer.detail has changed when distributed tracing is on. In the 8.4 - 8.7 PHP agent releases, newrelic.transaction_tracer.detail was disabled when distributed tracing was enabled. That is no longer the case. For more information, see the documentation for configuring trace level detail when using distributed tracing.
• To enable the improved support for distributed tracing, the PHP agent's memory allocation strategy has changed in 9.0. The PHP agent will more aggressively allocate memory when a transaction starts, and the system allocator may choose not to release that memory back to the operating system immediately, depending on the configuration of the operating system kernel and C library. As a result, the memory usage of the PHP processes may now be higher than it was with previous versions of the PHP agent.

Upgrade notices for 9.0

With these distributed tracing enhancements, please check threshold values.

• In the 8.4 - 8.7 PHP agent releases, we recommended that customers set newrelic.transaction_tracer.threshold = 0 so that the agent would report complete distributed traces even when a lightweight PHP service was part of the trace. This is no longer necessary.
• When upgrading to the 9.0 release, we recommend that you review your newrelic.transaction_tracer.threshold settings, and return this value to its default or some higher value that is sensible for the application.

The daemon will now issue a warning if it cannot find a root certificate bundle on startup.

• The daemon includes its own certificates and will still operate, but a future version of the PHP agent will remove the built-in certificates. At that point the PHP agent will not be able to communicate with New Relic's servers.
• Recommendation: Ensure a root certificate bundle is installed on your host or in your container before using the PHP agent. This is generally available on most Linux distributions as a ca-certificates package. On FreeBSD, a bundle is available via the security/ca_root_nss package in ports.

The daemon may no longer be invoked with the --tls flag.

• As of PHP agent version 8.0.0 the newrelic.daemon.ssl ini setting had been removed to increase security, but you could still invoke the daemon from the command line with --tls true. Command-line invocations of the daemon with the --tls flag will cause the invocation to fail.
• As with all PHP agent versions since 8.0.0, TLS is always used for communication with New Relic servers.

Bug fixes

• A potential segfault when using drupal_http_request under PHP 7.3 has been fixed.
• In some cases, starting a new transaction during a request (via newrelic_start_transaction or newrelic_set_appname) could result in an incomplete state of framework and user function instrumentation.
• When obfuscating SQL, comments are stripped without any loss of the SQL itself.
• Predis 0.8 commands that used the synchronous executeCommand() code path (for example, HSET) on a clustered connection did not generate metrics. This has been fixed.

Known issues and workarounds

Potential memory exhaustion for long running transactions

PHP agent 9.x uses more memory than previous versions, as it is less aggressive about freeing the memory used to track function calls and segments during transactions: in the normal case, memory is only freed at the end of each transaction.

This tends to manifest mainly for users with long running transactions, such as background jobs to process message queues, transform or report on data, or send e-mails.

We apologize for the inconvenience this issue has caused, and are actively working to fix it. In the short term, we have four potential workarounds to mitigate this issue.

Workarounds:

• 1. Start/stop transactions manually. If the affected transaction is one that performs a series of repetitive processes, such as a message queue consumer, you can manually instrument each iteration as a separate transaction. This provides you more fine-grained data on how the process is operating. By doing this, the memory used will be freed after each transaction. To implement this, you would ignore the initial automatic transaction with newrelic_end_transaction(true), then use newrelic_start_transaction()and newrelic_end_transaction() to instrument each transaction in turn.
• 2. Reduce transaction trace detail. If you will need PHP 7.4 immediately, or any of the functionality added in the PHP agent 9.x releases, and can get by with traces only including information on datastore and external calls, then you can reduce the level of detail the PHP agent captures by changing this configuration setting: newrelic.transaction_tracer.detail = 0. With this setting, traces will no longer contain PHP function calls. NOTE: Transactions that make hundreds of thousands of datastore or external calls may still be affected by memory issues.
• 3. Downgrade to PHP agent 8.7. If you don’t intend to use PHP 7.4 immediately, this is likely the simplest and fastest solution. To downgrade, you can either install from the tarballs at https://download.newrelic.com/php_agent/archive/8.7.0.242/, or downgrade to version 8.7.0.242 in your package manager and pin that version. Note that if distributed tracing is enabled on PHP agent 8.7, transaction tracer detail is automatically reduced (as per the next option).
• 4. Cap the # of function segments that are created (stay on PHP agent 9.x). This is similar to the “reduce transaction trace detail” option, but also allows for a limited number of PHP function calls to be traced, at the cost of an increase in memory usage commensurate with the number of functions that are captured. (As a rough rule of thumb, each segment requires about 320-400 bytes of the heap.) To capture the first 5,000 function calls, you would add this configuration setting: newrelic.transaction_tracer.max_segments = 5000. With this setting, any PHP functions after the number of function calls that are configured will be ignored. NOTE: Transactions that make hundreds of thousands of datastore or external calls may still be affected by memory issues.

**NOTE: A more detailed explanation of these options can be found in our Explorer’s Hub post.

Bug Fixes

• Transaction globals are now cleanly separated from request globals. This fixes crashes related to the initialization of multiple transactions during one request (mostly triggered by newrelic_set_appname()).

New Features

• Support Laravel's handling of CORS HTTP OPTIONS.
  Requests for Laravel's built-in automatic handling of CORS HTTP OPTIONS requests will now be given the transaction name _CORS_OPTIONS.

Bug Fixes

• A potential segfault when using PHP 7.3, opcache and multiple PHP workers has been fixed.
• Uncaught exceptions within a job being executed by a Laravel Queue worker are now reported correctly.
• Invoking function_exists() on a function disabled with the disable_functions configuration directive will now correctly return false.

New Features

• Added support for PHP 7.3.
  Keeping up with the latest and greatest from the PHP Core team, the New Relic PHP Agent now supports PHP 7.3.
• Distributed Tracing Improvements!
  The PHP Agent's Distributed Tracing support (introduced in version 8.4 of the PHP Agent) now includes the `http.method` attributes for External spans.
• Up to date PHPUnit support.
  The PHP Agent now supports automatic creation of custom events for PHPUnit 6, PHPUnit 7, and PHPUnit 8.

New Features

• Support for Distributed tracing

  Distributed tracing lets you see the path that a request takes as it travels through your distributed system. By showing the distributed activity through a unified view, you can troubleshoot and understand a complex system better than ever before.

  Distributed tracing is available with an APM Pro or equivalent subscription. To see a complete distributed trace, you need to enable the feature on a set of neighboring services. Enabling distributed tracing changes the behavior of some New Relic features, so carefully consult the transition guide before you enable this feature.

  To enable distributed tracing, two parameters should be changed in the newrelic.ini file:

  newrelic.distributed_tracing_enabled = true

  Copia

  and

  newrelic.transaction_tracer.threshold = 0

  Copia

  Read more about about distributed tracing in the PHP Agent.

Bug Fixes

• A bug in the PHP agent resulted in databaseCallCount attributes no longer being attached to Transaction events. The 8.4 release restores these attributes.
• Predis 2 cluster connections could not be instrumented due to internal changes in Predis. The 8.4 release fixes this.

Bug Fixes

• In rare cases, during a reset of the apache web server, the agent and mod_php would hang with 100% CPU utilization. This has been fixed.

Bug Fixes

• Fixed an entire category of bugs where a Drupal hook whose hook name matched its module name resulted in the generation of empty metric names.

Operating Systems Support

• This release of the PHP Agent removes support for the Solaris operating system. For Solaris support, please install agent version 8.1 or prior.

Upgrade Notices

• The PHP Agent API call newrelic_set_appname has been updated with security improvements in anticipation of future releases.

Upgrade Notices

• The newrelic.daemon.ssl ini setting has been removed to increase security. Transport Layer Security (TLS) will now always be used in communication with the New Relic collector.
• Laravel Queue support has now been enabled for all users. If newrelic.feature_flag=laravel_queue is set, it will now be ignored.

Bug Fixes

• On FreeBSD and Solaris, when newrelic.daemon.port is configured to use TCP to connect the agent to the daemon, the agent would have difficulty receiving application configuration data from the daemon due to the default timeout of 100 milliseconds matching the delay enforced by the FreeBSD kernel as part of its implementation of Nagle's algorithm. The PHP agent will now set the TCP_NODELAY flag when connecting to the daemon via TCP, which increases the reliability of the agent:daemon connection.