PHP agent release notesRSS

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.

Nuevas características en 9.0

Las trazas de la transacción detalladas ahora están disponibles cuando el rastreo distribuido está habilitado.

Esta versión incluye una refactorización del almacenamiento de segmentos para permitir que el agente ordene y aplique diferentes priorizaciones de segmentos que se utilizan para las trazas de la transacción en lugar del rastreo distribuido. La versión 8.4 del agente PHP incluyó soporte limitado para el rastreo distribuido, lo que resultó en la pérdida de trazas de la transacción detalladas para servicios PHP individuales cuando el rastreo distribuido estaba habilitado.

La refactorización en esta nueva versión permite al agente enviar los segmentos (spans) que desea ver para un rastreo distribuido que incluye servicios PHP. También proporciona por separado el mayor detalle posible de los segmentos al explorar las trazas de la transacción para un servicio PHP individual.

Notas:

• Las instrucciones para habilitar el rastreo distribuido no han cambiado con esta versión.
• El comportamiento de newrelic.transaction_tracer.detail ha cambiado cuando el rastreo distribuido está activado. En las versiones 8.4 - 8.7 del agente PHP, newrelic.transaction_tracer.detail estaba desactivado cuando el rastreo distribuido estaba activado. Esto ya no es así. Para obtener más información, consulte la documentación sobre cómo configurar el nivel de detalle de la traza al usar el rastreo distribuido.
• Para habilitar el soporte mejorado para el rastreo distribuido, la estrategia de asignación de memoria del agente PHP ha cambiado en la versión 9.0. El agente PHP asignará memoria de manera más agresiva cuando se inicie una transacción, y el asignador del sistema puede optar por no liberar esa memoria al sistema operativo de inmediato, dependiendo de la configuración del kernel del sistema operativo y la biblioteca de C. Como resultado, el uso de memoria de los procesos PHP ahora puede ser mayor que con versiones anteriores del agente PHP.

Avisos de actualización para 9.0

Con estas mejoras del rastreo distribuido, verifique los valores de los umbrales.

• En las versiones 8.4-8.7 del agente PHP, recomendamos que los clientes configuraran newrelic.transaction_tracer.threshold = 0 para que el agente reportara el rastreo distribuido completo incluso cuando un servicio PHP ligero fuera parte de la traza. Esto ya no es necesario.
• Al actualizar a la versión 9.0, le recomendamos que revise la configuración de newrelic.transaction_tracer.threshold y restablezca este valor a su valor por defecto o a un valor superior que sea adecuado para la aplicación.

El daemon ahora emitirá una advertencia si no puede encontrar un paquete de certificados raíz durante el inicio.

• El daemon incluye sus propios certificados y seguirá funcionando, pero una versión futura del agente PHP eliminará los certificados integrados. En ese momento, el agente PHP no podrá comunicarse con los servidores de New Relic.
• Recomendación: asegúrese de que haya un paquete de certificados raíz instalado en el host o en el contenedor antes de usar el agente PHP. Esto generalmente está disponible en la mayoría de las distribuciones de Linux como un paquete ca-certificates. En FreeBSD, hay un paquete disponible a través del paquete security/ca_root_nss en ports.

El daemon ya no se puede invocar con la bandera --tls.

• A partir de la versión 8.0.0 del agente PHP, la configuración ini newrelic.daemon.ssl se había eliminado para aumentar la seguridad, pero aún se podía invocar el daemon desde la línea de comando con --tls true. Las invocaciones de línea de comando del daemon con la bandera --tls harán que la invocación falle.
• Al igual que con todas las versiones del agente PHP desde la 8.0.0, TLS siempre se utiliza para la comunicación con los servidores de New Relic.

Corrección de errores

• Se ha solucionado un posible segfault al usar drupal_http_request en PHP 7.3.
• En algunos casos, iniciar una nueva transacción durante una solicitud (a través de newrelic_start_transaction o newrelic_set_appname) podría resultar en un estado incompleto del framework y de la instrumentación de la función del usuario.
• Al ofuscar SQL, los comentarios se eliminan sin ninguna pérdida del SQL en sí.
• Los comandos de Predis 0.8 que utilizaban la ruta de código executeCommand() síncrona (por ejemplo, HSET) en una conexión en clúster no generaban métricas. Esto se ha solucionado.

Problemas conocidos y soluciones alternativas

Posible agotamiento de memoria en transacciones de larga duración

El agente PHP 9.x usa más memoria que las versiones anteriores, ya que es menos agresivo a la hora de liberar la memoria utilizada para rastrear llamadas a funciones y segmentos durante las transacciones: en el caso normal, la memoria solo se libera al final de cada transacción.

Esto tiende a manifestarse principalmente en los usuarios con transacciones de larga duración, como trabajos en segundo plano para procesar colas de mensajes, transformar o generar informes sobre datos, o enviar correos electrónicos.

Pedimos disculpas por los inconvenientes que este problema ha causado y estamos trabajando activamente para solucionarlo. A corto plazo, tenemos cuatro posibles soluciones alternativas para mitigar este problema.

Soluciones alternativas:

• 1. Inicie/detenga las transacciones manualmente. Si la transacción afectada es una que realiza una serie de procesos repetitivos, como un consumidor de cola de mensajes, puede instrumentar manualmente cada iteración como una transacción independiente. Esto le proporciona datos más detallados sobre cómo opera el proceso. Al hacer esto, la memoria utilizada se liberará después de cada transacción. Para implementar esto, debería ignorar la transacción automática inicial con newrelic_end_transaction(true), y luego usar newrelic_start_transaction()y newrelic_end_transaction() para instrumentar cada transacción a su vez.
• 2. Reduzca el detalle de la traza de la transacción. Si necesita PHP 7.4 de inmediato, o cualquiera de las funcionalidades agregadas en las versiones 9.x del agente PHP, y le basta con trazas que solo incluyan información sobre el almacenamiento de datos y llamadas externas, entonces puede reducir el nivel de detalle que captura el agente PHP cambiando esta configuración: newrelic.transaction_tracer.detail = 0. Con esta configuración, las trazas ya no contendrán llamadas a funciones de PHP. NOTA: las transacciones que realizan cientos de miles de llamadas al almacenamiento de datos o externas aún pueden verse afectadas por problemas de memoria.
• 3. Desactualice al agente PHP 8.7. Si no tiene la intención de usar PHP 7.4 de inmediato, es probable que esta sea la solución más simple y rápida. Para desactualizar, puede instalar desde los tarballs en https://download.newrelic.com/php_agent/archive/8.7.0.242/, o desactualizar a la versión 8.7.0.242 en el administrador de paquetes y fijar esa versión. Tenga en cuenta que si el rastreo distribuido está habilitado en el agente PHP 8.7, el detalle del rastreador de transacciones se reduce automáticamente (según la siguiente opción).
• 4. Limite el número de segmentos de función que se crean (permanezca en el agente PHP 9.x). Esto es similar a la opción “reducir el detalle de la traza de la transacción”, pero también permite la traza de un número limitado de llamadas a funciones PHP, a costa de un aumento en el uso de memoria proporcional al número de funciones que se capturan. (Como regla general, cada segmento requiere unos 320-400 bytes del montón). Para capturar las primeras 5000 llamadas a funciones, agregaría esta configuración: newrelic.transaction_tracer.max_segments = 5000. Con esta configuración, se ignorará cualquier función PHP posterior al número de llamadas a funciones configuradas. NOTA: las transacciones que realizan cientos de miles de llamadas externas o al almacenamiento de datos aún pueden verse afectadas por problemas de memoria.

**NOTA: una explicación más detallada de estas opciones se puede encontrar en nuestra publicación de 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()).

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.