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.

Novos recursos na 9.0

Trace da transação detalhado agora disponível quando o distributed tracing está ativado.

Esta versão inclui uma refatoração do armazenamento de segmentos para permitir que o agente classifique e aplique diferentes priorizações de segmentos que são usados para traces da transação em vez de distributed tracing. A versão 8.4 do agente PHP incluiu suporte limitado para distributed tracing, o que resultou na perda de traces da transação detalhados para serviços PHP individuais quando o distributed tracing estava habilitado.

A refatoração nesta nova versão permite que o agente envie os segmentos (spans) que se deseja visualizar para um distributed trace que inclui serviços PHP. Ele também fornece separadamente o máximo de detalhes de segmento possível ao explorar o trace da transação para um serviço PHP individual.

Notas:

• As instruções para habilitar o distributed tracing não mudaram com esta versão.
• O comportamento de newrelic.transaction_tracer.detail mudou quando o distributed tracing está ativado. Nas versões 8.4–8.7 do agente PHP, newrelic.transaction_tracer.detail foi desativado quando o distributed tracing estava ativado. Esse não é mais o caso. Para obter mais informações, consulte a documentação sobre como configurar os detalhes de nível de trace ao usar o distributed tracing.
• Para ativar o suporte aprimorado para distributed tracing, a estratégia de alocação de memória do agente PHP mudou na versão 9.0. O agente PHP alocará memória de forma mais agressiva quando uma transação for iniciada, e o alocador do sistema pode optar por não liberar essa memória de volta para o sistema operacional imediatamente, dependendo da configuração do kernel do sistema operacional e da biblioteca C. Como resultado, o uso de memória dos processos PHP agora pode ser maior do que era com as versões anteriores do agente PHP.

Avisos de atualização para 9.0

Com essas melhorias no distributed tracing, verifique os valores de limite.

• Nas versões 8.4–8.7 do agente PHP, recomendamos que os clientes definissem newrelic.transaction_tracer.threshold = 0 para que o agente relatasse o distributed trace completo, mesmo quando um serviço PHP leve fizesse parte do trace. Isso não é mais necessário.
• Ao atualizar para a versão 9.0, recomendamos que as configurações de newrelic.transaction_tracer.threshold sejam revisadas e que esse valor retorne ao seu padrão ou a algum valor mais alto que seja adequado para o aplicativo.

O daemon agora emitirá um aviso se não conseguir encontrar um pacote de certificados raiz na inicialização.

• O daemon inclui seus próprios certificados e continuará operando, mas uma versão futura do agente PHP removerá os certificados integrados. Nesse momento, o agente PHP não poderá se comunicar com os servidores da New Relic.
• Recomendação: certifique-se de que um pacote de certificados raiz esteja instalado no host ou no contêiner antes de usar o agente PHP. Isso geralmente está disponível na maioria das distribuições Linux como um pacote ca-certificates. No FreeBSD, um pacote de certificados está disponível por meio do pacote security/ca_root_nss em ports.

O daemon não pode mais ser invocado com a flag --tls.

• A partir da versão 8.0.0 do agente PHP, a configuração ini newrelic.daemon.ssl foi removida para aumentar a segurança, mas ainda era possível invocar o daemon a partir da linha de comando com --tls true. As invocações de linha de comando do daemon com a flag --tls farão com que a invocação falhe.
• Como em todas as versões do agente PHP desde a 8.0.0, O TLS é sempre usado para comunicação com os servidores da New Relic.

Correções de bugs

• Uma possível falha de segmentação ao usar drupal_http_request no PHP 7.3 foi corrigida.
• Em alguns casos, iniciar uma nova transação durante uma solicitação (via newrelic_start_transaction ou newrelic_set_appname) pode resultar em um estado incompleto do framework e da instrumentação de função do usuário.
• Ao ofuscar o SQL, os comentários são removidos sem qualquer perda do próprio SQL.
• Os comandos do Predis 0.8 que usavam o caminho de código executeCommand() síncrono (por exemplo, HSET) em uma conexão em cluster não geravam métricas. O problema foi resolvido.

Problemas conhecidos e soluções alternativas

Possível esgotamento de memória para transações de longa duração

O agente PHP 9.x usa mais memória do que as versões anteriores, pois é menos agressivo na liberação da memória usada para rastrear chamadas de função e segmentos durante as transações: no caso normal, a memória só é liberada no final de cada transação.

Isso tende a se manifestar principalmente para usuários com transações de longa duração, como jobs em segundo plano para processar filas de mensagens, transformar ou relatar dados, ou enviar e-mails.

Pedimos desculpas pelo inconveniente que este problema causou e estamos trabalhando ativamente para resolvê-lo. A curto prazo, temos quatro possíveis soluções alternativas para mitigar este problema.

Soluções alternativas:

• 1. Iniciar/parar transações manualmente. Se a transação afetada for uma que executa uma série de processos repetitivos, como um consumidor de fila de mensagens, é possível instrumentar manualmente cada iteração como uma transação separada. Isso fornece dados mais detalhados sobre como o processo está operando. Ao fazer isso, a memória usada será liberada após cada transação. Para implementar isso, deve-se ignorar a transação automática inicial com newrelic_end_transaction(true) e, em seguida, usar newrelic_start_transaction()e newrelic_end_transaction() para instrumentar cada transação por sua vez.
• 2. Reduza os detalhes do trace da transação. Se for necessário o PHP 7.4 imediatamente, ou qualquer uma das funcionalidades adicionadas nas versões 9.x do agente PHP, e for suficiente o trace incluindo apenas informações sobre armazenamento de dados e chamadas externas, então é possível reduzir o nível de detalhes que o agente PHP captura alterando esta configuração: newrelic.transaction_tracer.detail = 0. Com esta configuração, o trace não conterá mais chamadas de função PHP. NOTA: Transações que fazem centenas de milhares de chamadas externas ou de armazenamento de dados ainda podem ser afetadas por problemas de memória.
• 3. Fazer o downgrade para o agente PHP 8.7. Caso não pretenda usar o PHP 7.4 imediatamente, esta é provavelmente a solução mais simples e rápida. Para fazer o downgrade, é possível instalar a partir dos tarballs em https://download.newrelic.com/php_agent/archive/8.7.0.242/, ou fazer o downgrade para a versão 8.7.0.242 no gerenciador de pacote e fixar essa versão. Vale ressaltar que, se o distributed tracing estiver ativado no agente PHP 8.7, o detalhe do tracer de transação é automaticamente reduzido (conforme a próxima opção).
• 4. Limite o número de segmentos de função que são criados (permaneça no agente PHP 9.x). Isso é semelhante à opção “reduzir detalhes do trace da transação”, mas também permite que seja feito o trace de um número limitado de chamadas de função PHP, à custa de um aumento no uso de memória proporcional ao número de funções que são capturadas. (Como regra geral, cada segmento requer cerca de 320–400 bytes do heap.) Para capturar as primeiras 5.000 chamadas de função, adicione esta definição de configuração: newrelic.transaction_tracer.max_segments = 5000. Com esta configuração, quaisquer funções PHP após o número de chamadas de função configuradas serão ignoradas. NOTA: Transações que fazem centenas de milhares de chamadas de armazenamento de dados ou externas ainda podem ser afetadas por problemas de memória.

**NOTA: Uma explicação mais detalhada dessas opções pode ser encontrada em nossa postagem no 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()).