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.

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 에이전트는 메모리를 더 적극적으로 할당하며, 운영 시스템 커널 및 C 라이브러리의 설정에 따라 시스템 할당자가 해당 메모리를 운영 시스템에 즉시 다시 해제하지 않도록 선택할 수 있습니다. 결과적으로 PHP 프로세스의 메모리 사용량이 이전 버전의 PHP 에이전트보다 더 높을 수 있습니다.

9.0 업그레이드 공지

이러한 분산 추적 개선 사항과 함께 임계값을 확인해 주십시오.

• 8.4～8.7 PHP 에이전트 릴리스에서는 경량 PHP 서비스가 트레이스의 일부인 경우에도 에이전트가 완전한 분산 트레이스를 보고하도록 고객이 newrelic.transaction_tracer.threshold = 0을(를) 설정할 것을 권장했습니다. 이는 더 이상 필요하지 않습니다.
• 9.0 릴리스로 업그레이드할 때 newrelic.transaction_tracer.threshold 설정을 검토하고 이 값을 기본값 또는 애플리케이션에 적합한 더 높은 값으로 되돌릴 것을 권장합니다.

이제 시작 시 루트 인증서 번들을 찾을 수 없으면 데몬에서 경고를 발생시킵니다.

• 데몬은 자체 인증서를 포함하고 있으며 계속 작동하지만, 향후 버전의 PHP 에이전트에서는 내장 인증서를 제거합니다. 그 시점이 되면 PHP 에이전트는 뉴렐릭의 서버와 통신할 수 없게 됩니다.
• 권장 사항: PHP 에이전트를 사용하기 전에 호스트 또는 컨테이너에 루트 인증서 번들이 설치되어 있는지 확인하십시오. 이는 일반적으로 대부분의 Linux 배포판에서 ca-certificates 패키지로 제공됩니다. FreeBSD에서는 포트의 security/ca_root_nss 패키지를 통해 번들을 사용할 수 있습니다.

데몬은 더 이상 --tls 플래그로 호출할 수 없습니다.

• PHP 에이전트 버전 8.0.0부터 보안을 강화하기 위해 newrelic.daemon.ssl ini 설정이 제거되었지만, 여전히 --tls true을(를) 사용하여 명령줄에서 데몬을 호출할 수 있었습니다. --tls 플래그를 사용한 데몬의 명령줄 호출은 실패합니다.
• 8.0.0 이후의 모든 PHP 에이전트 버전과 마찬가지로, 뉴렐릭 서버와의 통신에는 항상 TLS가 사용됩니다.

버그 수정

• PHP 7.3에서 drupal_http_request을(를) 사용할 때 발생할 수 있는 세그폴트가 수정되었습니다.
• 경우에 따라 요청 중(newrelic_start_transaction 또는 newrelic_set_appname을(를) 통해) 새 트랜잭션을 시작하면 프레임워크 및 사용자 기능 계측이 불완전한 상태가 될 수 있습니다.
• SQL을 난독화할 때 SQL 자체의 손실 없이 주석이 제거됩니다.
• 클러스터링된 연결에서 동기식 executeCommand() 코드 경로(예: HSET)를 사용한 Predis 0.8 명령은 메트릭을 생성하지 않았습니다. 이 문제가 수정되었습니다.

알려진 이슈 및 해결 방법

장기 실행 트랜잭션에 대한 잠재적인 메모리 고갈

PHP 에이전트 9.x는 트랜잭션 중 함수 호출 및 세그먼트를 추적하는 데 사용되는 메모리를 해제하는 데 덜 적극적이므로 이전 버전보다 더 많은 메모리를 사용합니다. 일반적인 경우 메모리는 각 트랜잭션이 끝날 때만 해제됩니다.

이는 주로 메시지 대기열 처리, 데이터 변환 또는 보고, 이메일 전송과 같은 백그라운드 작업 등 장기 실행 트랜잭션이 있는 사용자에게 나타나는 경향이 있습니다.

이 문제로 인해 불편을 끼쳐 드려 죄송하며, 문제를 해결하기 위해 적극적으로 노력하고 있습니다. 단기적으로 이 문제를 완화할 수 있는 네 가지 잠재적인 해결 방법이 있습니다.

해결 방법:

• 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/의 tarball에서 설치하거나 패키지 매니저에서 버전 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()).

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.