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.

Nouvelles fonctionnalités de la version 9.0

Des traces de transaction détaillées sont désormais disponibles lorsque le tracing distribué est activé.

Cette sortie inclut un refactoring du stockage des segments pour permettre à l’agent de trier et d’appliquer une priorisation différente des segments qui sont utilisés pour les traces de transaction au lieu du tracing distribué. La sortie de l’agent PHP 8.4 incluait une prise en charge limitée du tracing distribué, ce qui a entraîné la perte de traces de transaction détaillées pour les services PHP individuels lorsque le tracing distribué était activé.

Le refactoring dans cette nouvelle sortie permet à l’agent d’envoyer les segments (spans) que vous souhaitez visualiser pour des traces distribuées qui incluent des services PHP. Il fournit également séparément autant de détails de segment que possible lors de l’exploration de la trace de transaction pour un service PHP individuel.

Remarques :

• Les instructions pour activer le tracing distribué n’ont pas changé avec cette sortie.
• Le comportement de newrelic.transaction_tracer.detail a changé lorsque le tracing distribué est activé. Dans les sorties de l’agent PHP 8.4 - 8.7, newrelic.transaction_tracer.detail était désactivé lorsque le tracing distribué était activé. Ce n’est plus le cas. Pour plus d’informations, consultez la documentation sur la configuration du niveau de détail de trace lors de l’utilisation du tracing distribué.
• Pour activer la prise en charge améliorée du tracing distribué, la stratégie d’allocation de mémoire de l’agent PHP a changé dans la version 9.0. L’agent PHP allouera la mémoire de manière plus agressive lorsqu’une transaction démarre, et l’allocateur du système peut choisir de ne pas libérer cette mémoire au système d’exploitation immédiatement, en fonction de la configuration du noyau du système d’exploitation et de la bibliothèque C. Par conséquent, l’utilisation de la mémoire des processus PHP peut désormais être plus élevée qu’elle ne l’était avec les versions précédentes de l’agent PHP.

Notes de mise à niveau pour 9.0

Avec ces améliorations du tracing distribué, veuillez vérifier les valeurs de seuil.

• Dans les sorties 8.4 - 8.7 de l’agent PHP, nous avons recommandé aux clients de définir newrelic.transaction_tracer.threshold = 0 afin que l’agent rapporte des traces distribuées complètes même lorsqu’un service PHP léger faisait partie de la trace. Cela n’est plus nécessaire.
• Lors de la mise à niveau vers la sortie 9,0, nous vous recommandons de vérifier vos paramètres newrelic.transaction_tracer.threshold, et de remettre cette valeur à sa valeur par défaut ou à une valeur supérieure raisonnable pour l'application.

Le daemon émettra désormais un avertissement s’il ne trouve pas d’ensemble de certificats racine au démarrage.

• Le daemon inclut ses propres certificats et continuera de fonctionner, mais une future version de l’agent PHP supprimera les certificats intégrés. À ce stade, l’agent PHP ne sera pas en mesure de communiquer avec les serveurs de New Relic.
• Recommandation : assurez-vous qu’un bundle de certificats racine est installé sur votre hôte ou dans votre conteneur avant d’utiliser l’agent PHP. Ceci est généralement disponible sur la plupart des distributions Linux sous forme de package ca-certificates. Sur FreeBSD, un bundle est disponible via le package security/ca_root_nss dans les ports.

Le daemon ne peut plus être invoqué avec l’indicateur --tls.

• À partir de la version 8.0.0 de l’agent PHP, le paramètre ini newrelic.daemon.ssl avait été supprimé pour augmenter la sécurité, mais vous pouviez toujours invoquer le daemon depuis la ligne de commande avec --tls true. Les invocations en ligne de commande du daemon avec l’option --tls feront échouer l’invocation.
• Comme pour toutes les versions de l’agent PHP depuis la 8.0.0, TLS est toujours utilisé pour la communication avec les serveurs New Relic.

Débogage

• Une erreur de segmentation potentielle lors de l’utilisation de drupal_http_request sous PHP 7.3 a été corrigée.
• Dans certains cas, le démarrage d’une nouvelle transaction pendant une requête (via newrelic_start_transaction ou newrelic_set_appname) pourrait entraîner un état incomplet de l’instrumentation du framework et de la fonction utilisateur.
• Lors de l’obfuscation du code SQL, les commentaires sont supprimés sans aucune perte du code SQL lui-même.
• Les commandes Predis 0.8 qui utilisaient le chemin de code synchrone executeCommand() (par exemple, HSET) sur une connexion en cluster ne généraient pas de métriques. Ce problème a été résolu.

Problèmes connus et solutions de contournement

Épuisement potentiel de la mémoire pour les transactions de longue durée

L’agent PHP 9.x utilise plus de mémoire que les versions précédentes, car il est moins agressif pour libérer la mémoire utilisée pour suivre les appels de fonction et les segments pendant les transactions : dans le cas normal, la mémoire n’est libérée qu’à la fin de chaque transaction.

Cela a tendance à se manifester principalement pour les utilisateurs ayant des transactions de longue durée, telles que des tâches en arrière-plan pour traiter les files d’attente des messages, transformer, ou générer des rapports sur les données, ou envoyer des e-mails.

Nous vous présentons nos excuses pour les désagréments causés par ce problème, et travaillons activement pour le résoudre. À court terme, nous avons quatre solutions de contournement potentielles pour atténuer ce problème.

Solutions de contournement :

• 1. Démarrez/arrêtez les transactions manuellement. Si la transaction concernée est une transaction qui exécute une série de processus répétitifs, comme un consommateur de file d’attente des messages, vous pouvez instrumenter manuellement chaque itération comme une transaction distincte. Cela vous fournit des données plus précises sur le fonctionnement du processus. En faisant cela, la mémoire utilisée sera libérée après chaque transaction. Pour implémenter cela, ignorez la transaction automatique initiale avec newrelic_end_transaction(true), puis utilisez newrelic_start_transaction()et newrelic_end_transaction() pour instrumenter chaque transaction à tour de rôle.
• 2. Réduire les détails de la trace de transaction. Si vous avez besoin de PHP 7.4 immédiatement, ou de l’une des fonctionnalités ajoutées dans les sorties de l’agent PHP 9.x, et que vous pouvez vous contenter de traces n’incluant que des informations sur le datastore et les appels externes, vous pouvez alors réduire le niveau de détail que l’agent PHP capture en modifiant ce paramètre de configuration : newrelic.transaction_tracer.detail = 0. Avec ce paramètre, les traces ne contiendront plus d’appels de fonction PHP. REMARQUE : les transactions qui effectuent des centaines de milliers d’appels au datastore ou d’appels externes peuvent toujours être affectées par des problèmes de mémoire.
• 3. Rétrograder vers l’agent PHP 8.7. Si vous n’avez pas l’intention d’utiliser PHP 7.4 immédiatement, c’est probablement la solution la plus simple et la plus rapide. Pour rétrograder, vous pouvez soit installer à partir des archives tar à l’adresse https://download.newrelic.com/php_agent/archive/8.7.0.242/, soit rétrograder vers la version 8.7.0.242 dans votre gestionnaire de paquets et épingler cette version. Notez que si le tracing distribué est activé sur l’agent PHP 8.7, le détail du traceur de transaction est automatiquement réduit (conformément à l’option suivante).
• 4. Limitez le nombre de segments de fonction créés (restez sur l’agent PHP 9.x). Cela est similaire à l’option « réduire les détails de la trace de transaction », mais permet également de garder une trace d’un nombre limité d’appels de fonction PHP, au prix d’une augmentation de l’utilisation de la mémoire proportionnelle au nombre de fonctions capturées. (En règle générale, chaque segment nécessite environ 320-400 octets de tas.) Pour capturer les 5000 premiers appels de fonction, vous devez ajouter ce paramètre de configuration : newrelic.transaction_tracer.max_segments = 5000. Avec ce paramètre, toutes les fonctions PHP au-delà du nombre d’appels de fonction configurés seront ignorées. REMARQUE : Les transactions qui effectuent des centaines de milliers d’appels de datastore ou externes peuvent toujours être affectées par des problèmes de mémoire.

**REMARQUE : une explication plus détaillée de ces options se trouve dans notre publication sur l’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()).