PHP agent release notesRSS

Bug fixes

• A potential segfault when using PHP 7.4 in connection with framework instrumentation has been fixed.

Known issues and workarounds

Potential memory exhaustion for long running transactions

• See description and recommendations under Known issues and workarounds in the PHP 9.0.0.242 release notes.

Known issues and workarounds

Potential memory exhaustion for long running transactions

• See description and recommendations under Known issues and workarounds in the PHP 9.0.0.242 release notes.

New features in 9.4

Added support for PHP 7.4

• The PHP agent can detect libraries and frameworks that were preloaded via the opcache.preload setting.
  • You can disable this feature by using the following configuration setting: newrelic.preload_framework_library_detection = false.

Request URI attribute is now captured

• We now capture the request.uri attribute. The request URI appears in transaction queries in New Relic Insights.
  • You can disable this attribute by using the following configuration setting: newrelic.attributes.exclude = "request.uri".

Upgrade Notices

• For cross agent conformance, the agent attributes request.headers.User-Agent and httpResponseCode are renamed to request.headers.userAgent and response.statusCode. The value response.StatusCode is changed to an integer.
  • Attributes are reported with both the new and the legacy attribute names.
  • Support for legacy attribute names will be removed in future agent versions.

Bug Fixes

• Since 9.0, transaction traces and span events were not created when newrelic_end_transaction was called inside a PHP function. newrelic_end_transaction now creates transaction traces and span events in any case. It reports all traces and span events for segments that weren't ended at the time of its invocation as unknown.

• Since 9.0, Predis calls weren't instrumented when the Predis client was loaded from a path ending in Predis/Client.php. This has been fixed.

• For inbound distributed tracing payloads with invalid or missing values for pr (priority) and/or sa (sampled) the agent used to assign a default priority of -1 and/or a default sampled value of false to the transaction.

  • This has been fixed, the agent now keeps initial priority and sampled values if the respective values in the inbound distributed tracing payload are missing or invalid.

• The daemon used to erroneously send SIGUSR1 signals to its parent process group in case one of the flags --foreground or --watchdog-foreground was given. This has been fixed.

Known issues and workarounds

Potential memory exhaustion for long running transactions

• See description and recommendations under Known issues and workarounds in the PHP 9.0.0.242 release notes.

New features in 9.3

Trace and entity metadata API calls

• A new API function newrelic_is_sampled() has been added. This call returns true if the current transaction is part of a sampled distributed trace.
• A new API function for obtaining linking metadata been added. newrelic_get_linking_metadata(). This call returns an opaque map of key/value pairs that can be used to correlate this application to other data in the New Relic backend.
• A new API function newrelic_get_trace_metadata() has been added. This call returns a collection of metadata used to identify a trace: trace.id, which provides the currently executing trace's identifier; and span.id, which provides the span identifier associated with the currently executing span.

Configurable connection timeout

• The PHP agent has introduced a new configuration newrelic.daemon.app_connect_timeout. Customers may use this to specify a timeout for the agent to wait for a daemon connection.

  With this timeout set, the agent will not immediately drop a transaction when the daemon hasn't connected to the backend yet, but rather grant the daemon time to establish the connection.

  It is recommended to only set this timeout when instrumenting long-lived background tasks, as in case of connection problems the agent will block for the given timeout at every transaction start.

New features in 9.2

More flexibility for container deployments

• The PHP daemon and agent no longer have to reside on the same host and can now communicate over a IPv4 or IPv6 TCP socket. This can be configured via the newrelic.daemon.address setting in the agent and the --address command line option for the daemon.
• When terminating the New Relic PHP daemon via the SIGTERM signal (and/or the SIGINT signal if started with the -f, --foreground flag), the daemon will now send all buffered data to New Relic prior to exiting.
• The PHP daemon has introduced a new configuration --watchdog-foreground. This keeps the daemon watchdog process in the foreground, whereas the --foreground configuration keeps the daemon worker process in the foreground. The new configuration makes it possible to use the daemon in a blocking way, without losing the additional stability provided by the watchdog process.

Upgrade notices

• The PHP agent has introduced a new configuration newrelic.daemon.address which serves as an alias to newrelic.daemon.port. You may use either to specify the location of the New Relic PHP daemon. If both values are set, newrelic.daemon.address takes precedence.

  Similarly, the PHP daemon has introduced a new configuration --address which serves as an alias to --port. Customers may use either to specify the location of the New Relic PHP daemon. If both values are set, --address takes precedence.

• When starting the daemon as an external process, the daemon will now wait for up to three seconds for the listening port to be ready to receive connections before forking into the background. This usually occurs in (much) less than a second, and most users with this configuration will notice no difference in practice.

  The time that the daemon will wait can be controlled by setting the --wait-for-port setting with a duration. This duration may be 0 to prevent any blocking. If the option is omitted, the default value is 3s.

  Note that this is not the default configuration shipped with the PHP agent, and generally is only used in conjunction with the PHP agent configured with newrelic.daemon.dont_launch set to 3.

  Daemons started in foreground mode (with the --foreground flag) are unaffected, and will behave as before.

Bug fixes

• When duplicating database connections to generate explain plans, the agent will no longer make those connections persistent, even if the original connection was persistent.
• The daemon now synchronously handles critical code paths related to harvesting and merging transaction data. This prevents crashes caused by race conditions.
• Previously, the PHP agent was silently ignoring the setting newrelic.daemon.port if the value was outside of the range 1 - 65535. In this case, it used the default value of /tmp/.newrelic.sock. The PHP agent no longer silently ignores these port values; it now logs these errors in php_agent.log.

Known issues and workarounds

• Potential memory exhaustion for long running transactions. See description under Known issues and workarounds in the PHP 9.0.0.242 release notes.

New Features in 9.1

Symfony 4 support added.

• Web transactions that use the Symfony 4 framework will now be automatically named based on the route or controller name.

Addition of the ability to migrate to Configurable Security Policies (CSP) on a per agent basis for accounts already using High-security mode (HSM).

• When both HSM and CSP are enabled for an account, an agent (this version or later) can successfully connect with either high_security: true or the appropriate security_policies_token configured.

Upgrade notices

• Requests handled by PHP-FPM that result in a 404 error because the script does not exist, or a 403 error because PHP-FPM does not have permission to access the script, will now result in a transaction called 404 or 403, respectively, rather than being named after the request URI. This change was made to prevent metric grouping issues, particularly when sites are being probed by potential attackers.

  If you wish to capture the actual request URI for analysis, it can be attached to the transaction event under the request.uri attribute using the following configuration setting: newrelic.transaction_events.attributes.include=request.uri

Bug fixes

• In version 9.0, Guzzle and Predis execution time could be double counted on application overview and transaction charts in APM, as time could be attributed to both PHP execution and the external or datastore time, respectively. This has been fixed, and charts should now revert back to their previous behavior.
• Restarting a transaction from within a Drupal or WordPress hook could result in a segfault. This has been fixed.

Known issues and workarounds

• Potential memory exhaustion for long running transactions. See description under Known issues and workarounds in the PHP 9.0.0.242 release notes.

Notes

• A bug that could result in segfaults when transactions were restarted (either directly through newrelic_start_transaction() or indirectly through newrelic_set_appname()) was fixed.

  This also affected customers using Laravel Queue instrumentation, as this uses transaction restarts internally.

• PHPUnit may not have been detected on case sensitive filesystems on 9.0.0. This has been fixed.

• A bug that could result in segfaults for CodeIgniter applications on PHP 7 when call_user_func_array() inlining failed was fixed.

Known issues and workarounds

• Potential memory exhaustion for long running transactions. See description under Known issues and workarounds in the PHP 9.0.0.242 release notes.

9.0の新機能

ディストリビューティッド（分散）トレーシングを有効にした場合、詳細なトランザクショントレースが利用可能になりました。

このリリースには、エージェントがディストリビューティッド（分散）トレーシングの代わりにトランザクショントレースに使用されるセグメントをソートし、異なる優先順位を適用できるようにするためのセグメントストレージのリファクタリングが含まれています。PHPエージェント8.4のリリースには、ディストリビューティッド（分散）トレーシングの限定的なサポートが含まれていましたが、これにより、ディストリビューティッド（分散）トレーシングが有効になっている場合、個々のPHPサービスの詳細なトランザクショントレースが失われる結果となりました。

この新しいリリースでのリファクタリングにより、PHPサービスを含むディストリビューティッド（分散）トレーシングについて、表示したいセグメント（スパン）をエージェントが送信できるようになりました。また、個々のPHPサービスのトランザクショントレースを調査する際に、可能な限り詳細なセグメント情報を個別に提供します。

メモ：

• このリリースでは、ディストリビューティッド（分散）トレーシングを有効にする手順に変更はありません。
• ディストリビューティッド（分散）トレーシングがオンの場合、newrelic.transaction_tracer.detailの動作が変更されました。8.4～8.7のPHPエージェントリリースでは、ディストリビューティッド（分散）トレーシングが有効になっている場合、newrelic.transaction_tracer.detailは無効になっていました。現在はそうではありません。詳細については、ディストリビューティッド（分散）トレーシングを使用する際のトレースレベルの詳細の設定のドキュメントをご覧ください。
• ディストリビューティッド（分散）トレーシングのサポート向上を有効にするため、9.0ではPHPエージェントのメモリ割り当て戦略が変更されました。トランザクションの開始時にPHPエージェントはより積極的にメモリを割り当てます。また、OSカーネルおよびCライブラリの設定によっては、システムアロケータがそのメモリをすぐにOSに解放しない場合があります。その結果、PHPプロセスのメモリ使用量が、以前のバージョンのPHPエージェントよりも高くなる場合があります。

9.0のアップグレードに関する注意事項

これらのディストリビューティッド（分散）トレーシングの強化に伴い、閾値を確認してください。

• 8.4～8.7のPHPエージェントのリリースでは、軽量なPHPサービスがトレースの一部である場合でも、エージェントが完全なディストリビューティッド（分散）トレーシングを報告するように、顧客にnewrelic.transaction_tracer.threshold = 0を設定することを推奨していました。これは不要になりました。
• 9.0リリースにアップグレードする際は、newrelic.transaction_tracer.thresholdの設定を確認し、この値をデフォルト値、またはアプリケーションにとって適切なより高い値に戻すことをお勧めします。

起動時にルート証明書バンドルが見つからない場合、デーモンは警告を出すようになりました。

• デーモンには独自の証明書が含まれており、引き続き動作しますが、PHPエージェントの将来のバージョンでは組み込みの証明書が削除されます。その時点で、PHPエージェントはNew Relicのサーバーと通信できなくなります。
• 推奨：PHPエージェントを使用する前に、ホストまたはコンテナにルート証明書バンドルがインストールされていることを確認してください。これは通常、ほとんどのLinuxディストリビューションでca-certificatesパッケージとして利用できます。FreeBSDでは、portsのsecurity/ca_root_nssパッケージを介してバンドルを利用できます。

デーモンは、--tlsフラグを使用して呼び出すことができなくなりました。

• PHPエージェントバージョン8.0.0の時点で、セキュリティ向上のためnewrelic.daemon.ssl ini設定は削除されていましたが、引き続きコマンドラインから--tls trueを使用してデーモンを呼び出すことができました。--tlsフラグを使用したコマンドラインからのデーモンの呼び出しは失敗します。
• 8.0.0以降のすべてのPHPエージェントバージョンと同様に、New Relicサーバーとの通信には常にTLSが使用されます。

バグ修正

• PHP 7.3でdrupal_http_requestを使用した場合の潜在的なセグメンテーションフォールトが修正されました。
• 場合によっては、リクエスト中に（newrelic_start_transactionまたはnewrelic_set_appnameを介して）新しいトランザクションを開始すると、フレームワークおよびユーザー関数の計装が不完全な状態になる可能性があります。
• SQLを難読化する際、SQL自体を損なうことなくコメントが削除されます。
• クラスター化された接続で同期executeCommand()コードパス（たとえば、HSET）を使用するPredis 0.8コマンドは、メトリクスを生成しませんでした。これは修正されました。

既知の問題と回避策

長時間実行されるトランザクションによる潜在的なメモリ枯渇

PHPエージェント9.xは、トランザクション中の関数呼び出しやセグメントの追跡に使用されるメモリの解放に消極的であるため、以前のバージョンよりも多くのメモリを使用します：通常の場合、メモリは各トランザクションの終了時にのみ解放されます。

これは主に、メッセージキューを処理するバックグラウンドジョブ、データの変換やレポート作成、電子メールの送信など、実行時間の長いトランザクションを持つユーザーに現れる傾向があります。

この問題によりご不便をおかけして申し訳ありません。現在、修正に向けて積極的に取り組んでいます。短期的には、この問題を軽減するための4つの可能な回避策があります。

回避策：

• 1. トランザクションを手動で開始/停止します。影響を受けるトランザクションが、メッセージキューの消費者など、一連の反復プロセスを実行するものである場合、各反復を個別のトランザクションとして手動で計装できます。これにより、プロセスがどのように動作しているかについて、よりきめ細かいデータが得られます。これを行うことで、使用されたメモリは各トランザクションの後に解放されます。これを実装するには、newrelic_end_transaction(true)による最初の自動トランザクションを無視し、newrelic_start_transaction()とnewrelic_end_transaction()を使用して各トランザクションを順番に計装します。
• 2. トランザクショントレースの詳細を減らす。PHP 7.4、またはPHPエージェント9.xリリースで追加された機能がすぐに必要であり、データストアと外部呼び出しに関する情報のみを含むトレースで十分な場合は、次の設定を変更することで、PHPエージェントがキャプチャする詳細レベルを下げることができます：newrelic.transaction_tracer.detail = 0。この設定により、トレースにはPHP関数呼び出しが含まれなくなります。注：数十万回のデータストアまたは外部呼び出しを行うトランザクションは、依然としてメモリの問題の影響を受ける可能性があります。
• 3. PHPエージェント8.7にダウングレードします。すぐにPHP 7.4を使用する予定がない場合、これが最も簡単で最速の解決策になる可能性があります。ダウングレードするには、https://download.newrelic.com/php_agent/archive/8.7.0.242/のtarボールからインストールするか、パッケージマネージャでバージョン8.7.0.242にダウングレードしてそのバージョンを固定します。PHPエージェント8.7でディストリビューティッド（分散）トレーシングが有効になっている場合、トランザクショントレーサーの詳細は（次のオプションに従って）自動的に削減されることにご注意ください。
• 4. 作成される関数セグメントの数を制限します（PHPエージェント9.xを維持します）。これは「トランザクショントレースの詳細を減らす」オプションに似ていますが、キャプチャされる関数の数に見合ったメモリ使用量の増加を犠牲にして、限られた数のPHP関数呼び出しをトレースすることもできます。（大まかな経験則として、各セグメントには約320～400バイトのヒープが必要です。）最初の5,000回の関数呼び出しをキャプチャするには、この設定を追加します：newrelic.transaction_tracer.max_segments = 5000。この設定により、設定された関数呼び出し回数以降のPHP関数は無視されます。注：数十万回のデータストアまたは外部呼び出しを行うトランザクションは、依然としてメモリの問題の影響を受ける可能性があります。

**注：これらのオプションの詳細な説明については、Explorer's Hubの投稿をご覧ください。

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()).