Ruby 에이전트 6.x에서 7.x로 마이그레이션 가이드

요약

이 가이드는 Ruby 에이전트의 6.x와 7.x 시리즈 사이의 주요 변경 사항, 업그레이드하는 동안 발생할 수 있는 문제, 버전 7.x로 성공적으로 마이그레이션하는 방법을 다룹니다.

주요 변경 사항은 다음과 같습니다.

Ruby 2.0 및 2.1 지원 중단
SSL 인증서 번들이 제거되었습니다.
다양한 6.x 릴리스에서 더 이상 사용되지 않는 여러 API가 이제 제거되었습니다.
자동 계측은 기본적으로 메서드 체인보다 앞에 추가됩니다.
자동 계측은 일관된 구성 속성을 얻습니다.

Ruby 2.0 및 2.1 지원 중단

Ruby 2.0 및 2.1은 2016년 2월에 EOL에 도달했으며 New Relic은 7.0 릴리스에서 이러한 버전에 대한 지원을 중단하면서 그 뒤를 잇고 있습니다. 본질적으로 이러한 버전이 계속 작동하는 것을 방해하는 알려진 변경 사항은 없지만 앞으로 Ruby 에이전트가 문제 없이 계속 작동한다고 더 이상 보장하지 않습니다. Ruby 2.0 또는 2.1이 필요한 경우 이러한 Ruby 버전을 지원하기 위해 게시된 마지막 릴리스인 6.15.0을 계속 사용하십시오.

계측 구성 앞에 추가

관련 pull 요청: 계측 #565 를 추가합니다.

잠재적인 문제: 에이전트가 데이터 보고를 초기화하고 시작하지 못합니다. 스택 수준이 너무 깊다는 오류 메시지가 로그에 보고됩니다.

솔루션: 이제 구성을 통해 구성 및 종속성 감지 메커니즘을 제어할 수 있습니다. 기본적으로 모든 자동 계측 보석/라이브러리는 prepend 전략으로 활성화됩니다. 구성 파일에 설정이 표시되지 않는 경우 이러한 라이브러리에 대한 기본 구성 설정은 auto 이며 최상의 전략을 선택합니다. prepend 전략과 알려진 충돌의 경우 auto 은 이러한 충돌이 감지될 때 메서드 체인으로 폴백하도록 에이전트에 지시합니다. 다음은 sidekiq를 예로 사용하여 자동 계측을 위한 구성 섹션의 변경 사항에 대한 전체 설명입니다.

instrumentation:
    sidekiq: chain

팁

이에 대한 사용 사례는 알 수 없는 보석이 충돌하는 것으로 확인되는 경우입니다. 사용자는 충돌을 자동 감지하고 처리하도록 에이전트를 업데이트할 수 있을 때까지 충돌을 처리하기 위해 메서드 체인으로 되돌릴 수 있습니다.

계측을 완전히 비활성화하려면:

instrumentation:
    sidekiq: disable

어떤 경우에는 특정 보석이 prepend와 충돌한다는 것을 알 수 있습니다. 이를 용이하게 하기 위해 기본적으로 자동 구성 옵션을 제공하며, 이러한 경우 자동으로 체인으로 저하됩니다.

대부분의 경우 기본 설정은 다음과 같습니다.

instrumentation:
    sidekiq: auto

구성 파일에 지정하여 prepend 전략을 사용하도록 강제할 수 있습니다.

instrumentation:
    sidekiq: prepend

팁

이에 대한 사용 사례는 충돌하는 gem의 최신 버전이 출시되고 더 이상 prepend 전략과 충돌하지 않는 것으로 알려진 경우입니다.

스택 수준이 너무 깊은 오류가 발생하면 이러한 문제를 해결하는 방법에 대한 문제 해결 가이드 를 참조하세요. 이 문제 해결 가이드를 통해 작업한 후 이 GitHub 문제 에 댓글을 달아 발견한 접두사 충돌에 대해 알려주실 수 있습니다. 이러한 시나리오에서 메서드 연결을 감지하고 자동으로 대체할 수 있도록 귀하의 피드백에 감사드립니다.

현대화된 자동 계측 전략

Ruby는 prepend를 사용하여 원본 gem 라이브러리의 구현을 trace/ 관찰 가능성 논리.

메서드 체인(method_alias 원숭이 패치라고도 함)과 접두어를 혼합하면 해당 주제에 대한 블로그 게시물 에 설명된 대로 알려진 스택 수준이 너무 깊은 시나리오로 이어질 수 있습니다.

New Relic은 이전에 prepend 전략을 사용하기 위해 수년에 걸쳐 많은 자동 계측 라이브러리를 업데이트했습니다. 7.0 릴리스에서는 스택 수준이 너무 깊은 오류를 유발하는 알려진 시나리오가 있는 경우를 제외하고 메서드 연결을 통해 자동 계측을 선택하는 기본 전략을 앞에 추가합니다. 이 시나리오로 이어질 수 있는 충돌하는 외부 보석을 식별하기 위한 최선의 노력이 있었지만 확인하지 않은 다른 보석이 야생에 있을 수밖에 없습니다.

과거에는 대부분의 보석에 대해 자동 계측을 수행하는 방법이 한 가지뿐이었으며 바로 메서드 체인이었습니다. 7.0 릴리스에서는 메서드 연결 또는 추가를 사용하여 대부분의 gem을 계측할 수 있으며 모든 자동 계측 gem의 구성이 이를 반영하도록 업데이트되었습니다.

자동 계측의 현대화와 함께 종속성 감지 메커니즘에 새로운 기능을 도입하여 충돌하는 외부 보석을 식별하고 추가 전략에서 메서드 체인으로 자동 전환합니다. 즉, 보석과 함께 Ruby 에이전트를 사용하기 쉽게 하기 위해 보석 라이브러리를 변경하기 위해 다른 보석의 유지 관리자에게 더 이상 의존할 필요가 없습니다. 그러나 사용자가 보고할 때까지 이러한 충돌을 인식하지 못하므로 자동 계측 라이브러리 중 일부만이 이러한 충돌을 자동으로 감지하고 메서드 체인 전략으로 자동 전환할 수 있습니다. 이러한 시나리오에 대해 듣고 향후 Ruby 에이전트 릴리스에 자동 감지를 추가하려면 여러분의 도움이 필요합니다.

SSL 인증서 번들이 제거되었습니다.

Ruby 초기(1.8, 1.9 등)에는 OpenSSL과의 통합 및 HTTPS 연결이 제대로 처리되지 않았습니다. 고객이 New Relic의 Collector 서버에 지속적으로 HTTPS 연결을 할 수 있도록 하기 위해 SSL CA 인증서를 번들로 제공하고 Ruby 에이전트와 함께 배포했습니다. 시간이 지남에 따라 Ruby 에코시스템은 안정화되었으며 이제 인증서 번들을 번들로 배포하고 배포할 필요가 거의 없는 표준 방식으로 시스템에 설치된 CA 인증서를 지원합니다. 번들로 제공되는 대부분의 인증서가 만료되었거나 만료가 임박했으므로 에이전트에서 이 종속성을 제거하기로 결정했습니다. CA 인증서가 설치되지 않은 컨테이너 또는 서버에 Ruby 애플리케이션 및 에이전트를 배포하는 경우 New Relic 서버에 대한 성공적인 HTTPS 연결을 위해 에이전트의 7.0 이상 릴리스에 대해 현재 설치되어 있는지 확인해야 합니다.

자세한 내용은 인증서 번들 #478 제거 를 참조하세요.

잠재적인 문제: OpenSSL 및 시스템 CA 인증서가 설치되지 않은 호스트에 배포하는 경우 New Relic 서버에 연결하는 데 문제가 발생하고 APM 데이터가 손실될 수 있습니다.

솔루션: New Relic 서버에는 성공적인 연결을 시작하기 위해 CA 인증서를 사용하는 HTTPS가 필요합니다. 이들은 호스트에 따라 다양한 방식으로 설치될 수 있습니다. 다음은 호스트의 준비 상태를 테스트하고 CA 인증서를 설치하는 데 유용한 링크입니다.

필요한 경우 구성을 통해 CA 번들 파일에 대한 경로를 제공하여 모든 CA 번들을 사용하도록 에이전트를 구성할 수 있습니다. :ca_bundle_path . 자세한 내용 은 Ruby용 사용자 지정 SSL 인증서를 참조하세요.

더 이상 사용되지 않는 API 및 구성 속성

더 이상 사용되지 않는 모든 API에는 더 이상 사용되지 않는 API의 범위를 확장하거나 견고성을 향상시키는 대체 API가 있습니다.

관련 pull 요청은 다음과 같습니다.

거부 및 허용 목록 사용

잠재적인 문제: 흑백 목록 속성이 더 이상 작동하지 않습니다.

솔루션 : 구성 또는 환경 변수 설정에서 black 을 denied 로, white 를 allowed 으로 변경합니다.

https://docs.newrelic.com/docs/apm/agents/ruby-agent/configuration/ruby-agent-configuration/#autostart-denylisted_constants

:autostart.blacklisted_constants => :autostart.denylisted_constants
:autostart.blacklisted_executables => :autostart.denylisted_executables
:autostart.blacklisted_rake_tasks => :autostart.denylisted_rake_tasks
:strip_exception_messages.whitelist => :strip_exception_messages.allowed_classes

활성 레코드

잠재적인 문제: 이전 Active Record 버전 비활성화가 더 이상 작동하지 않습니다.

해결 방법: 다음 구성 설정을 변경합니다.

:disable_active_record_4 => :disable_active_record_notifications
:disable_active_record_5 => :disable_active_record_notifications

httpResponseCode

잠재적인 문제: httpResponseCode 속성이 보고된 추적의 UI에 더 이상 표시되지 않습니다.

솔루션: httpResponseCode 이(가)http.statusCode 으)로 대체되었습니다.

알림 오류(trace_only)

잠재적인 문제: :trace_only 옵션을 NewRelic::Agent.notice_error 에 전달하면 더 이상 작동하지 않습니다.

솔루션: :trace_only 을:expected 속성으로 바꿉니다.

분산 추적 API

잠재적인 문제: API 메서드 create_distributed_trace_payload 및 accept_distributed_trace_payload 을 호출하는 동안 애플리케이션 코드에서 오류가 발생합니다.

해결 방법: 대신 각각 insert_distributed_trace_headers 및 accept_distributed_trace_headers 을(를) 참조하십시오.

이 한글 문서는 사용자의 편의를 위해 기계 번역되었습니다.