Rubyエージェント6.xから7.xへの移行ガイド

概要

このガイドでは、Rubyエージェントの6.xシリーズと7.xシリーズの主な変更点、アップグレード時に発生する可能性のある問題、およびバージョン7.xへの移行を成功させる方法について説明します。

主な変更点は以下の通りです。

Ruby 2.0および2.1のサポートを終了しました。
SSL Certificate Bundleの削除
様々な6.xリリースで非推奨となっていたいくつかのAPIが削除されました。
オートインストルメントでは、メソッドチェイニングよりもプリペンドがデフォルトとなる
オートインストルメントで一貫した設定属性を取得

詳細は、7.0ターゲットリリースのマイルストーン（）をご参照ください。

Ruby 2.0および2.1のサポートを終了しました。 [#ruby-2-dropped]

Ruby 2.0 および 2.1 は 2016 年 2 月に EOL に達しており、New Relic もそれに倣って 7.0 リリースでこれらのバージョンのサポートを停止します。これらのバージョンが本質的に機能し続けることを妨げるような既知の変更はありませんが、今後もRubyエージェントが問題なく機能し続けることを保証するものではありません。Ruby 2.0 または 2.1 が必要な場合は、これらの Ruby バージョンをサポートする最後のリリースである 6.15.0 を引き続きご利用ください。

インストルメンテーションの設定を前もって行う

Relevant pull request: Prepend instrumentation #565.

Potential issue: エージェントは初期化に失敗し、データのレポートを開始できません。スタックレベルが深すぎるというエラーメッセージがログに報告されます。

Solution: 設定および依存関係検出メカニズムは、設定を通じて制御できるようになりました。デフォルトでは、自動インストゥルメントされたすべての gems/ライブラリは prepend 戦略でアクティブ化されます。構成ファイルに設定がない場合、これらのライブラリのデフォルトの構成設定はautoであり、最適な戦略が選択されます。先頭追加戦略との既知の競合の場合、 auto 、そのような競合が検出されたときにメソッドチェーンにフォールバックするようにエージェントに指示します。以下は、sidekiq を例にして、自動インストゥルメンテーションの設定セクションに加えた変更の詳細な説明です。

instrumentation:
    sidekiq: chain

ヒント

使用例としては、未知のgemがコンフリクトしていることが判明した場合です。エージェントがコンフリクトを自動検出して処理するように更新されるまで、ユーザーはコンフリクトを処理するためにメソッド・チェインに戻すことができます。

インストゥルメンテーションを完全に無効にするには

instrumentation:
    sidekiq: disable

場合によっては、特定のジェムがprependと競合することがあります。このような場合には、自動的にchainにデグレードする自動設定オプションをデフォルトで提供しています。

ほとんどの場合、初期設定はこのようになっています。

instrumentation:
    sidekiq: auto

設定ファイルでprepend戦略を指定することで、強制的にprepend戦略を使用することができます。

instrumentation:
    sidekiq: prepend

ヒント

この使用例は、競合するgemの新しいバージョンがリリースされ、prepend戦略との競合がなくなったことがわかっている場合です。

スタックレベルが深すぎるというエラーが発生した場合は、これらの問題を解決する方法について、トラブルシューティングガイドを参照してください。このトラブルシューティングガイドを実行した後、このGitHub の問題にコメントして、見つかったプリペンドの競合についてお知らせください。このようなシナリオでは、メソッドチェーンを検出して自動的にメソッドチェーンにフォールバックできるよう、フィードバックをお待ちしております。

オートインストルメント戦略の近代化

Rubyでは、2013年にリリースされたRuby 2.0において、メソッド定義をメソッド解決スタックの前段に挿入する手段としてprependが導入されました。これは、オリジナルのgemライブラリの実装にtrace/observabilityロジックを適用する際に、prependによってメソッドチェインを行う必要がなくなることを意図したものです。

prependとmethod-chainを混在させると（method_alias monkey patching）、のブログ記事で説明されているように、スタックレベルが深すぎるという既知のシナリオに陥る可能性があります。

New Relic はこれまでに、多くの自動インストルメントライブラリを prepend 戦略を使用するようにアップデートしてきました。7.0のリリースでは、スタックレベルが深すぎるというエラーを引き起こす可能性がある既知のシナリオを除いて、メソッドチェインではなくプリペンドをデフォルトのストラテジーとして自動計測を行うようになりました。このシナリオにつながる矛盾した外部ジェムを特定するための最善の努力がなされましたが、私たちが特定していない他のものも存在するはずです。

これまでは、ほとんどのGemを自動インストルメント化する方法は、メソッド・チェイニングしかありませんでした。7.0のリリースでは、ほとんどのGemをmethod-chainまたはprependのいずれかを使用してインストゥルメントすることができ、自動インストゥルメントされたすべてのGemの設定がこれを反映して更新されました。

自動計測機能の近代化に伴い、依存性検出メカニズムにも新しい機能を導入しました。これにより、競合する外部ジェムを特定し、プリペンド戦略からメソッド・チェイニングへと自動的に切り替えることができます。これにより、他のgemのメンテナが、それらのgemと一緒にRubyエージェントを使いやすくするために、gemライブラリに変更を加えることに依存する必要がなくなりました。しかし、このような競合はユーザーから報告されるまでわかりません。そのため、これらの競合を自動検出してメソッド・チェイニング戦略に自動的に切り替えることができるのは、自動計測されたライブラリのうちのいくつかに限られます。このようなシナリオを聞き、将来のRubyエージェントのリリースに自動検出機能を追加するためには、皆様のご協力が必要です。

SSL証明書のバンドルが削除される

Ruby (1.8、1.9 など) の初期の頃、OpenSSL との統合と HTTPS 接続の作成は適切に処理されていませんでした。顧客が New Relic の Collector サーバーへの HTTPS 接続を一貫して確立できるようにするために、選択した SSL CA 証明書がバンドルされ、Ruby エージェントに配布されました。時間が経つにつれて、Ruby エコシステムは安定し、現在ではシステムにインストールされた CA 証明書を標準的な方法でサポートしています。これにより、証明書バンドルをバンドルして配布する必要性が大幅に時代遅れになりました。バンドルされている証明書の大部分は期限切れになっているか、期限切れに近づいているため、この依存関係をエージェントから削除することにしました。Ruby アプリケーションとエージェントを、CA 証明書がインストールされていないコンテナーまたはサーバーにデプロイする場合、New Relic サーバーへの HTTPS 接続を成功させるには、エージェントの 7.0 以降のリリース用にそれらがインストールされていることを確認する必要があります。

詳しくは、 Remove cert bundle #478 をご覧ください。

Potential issue: OpenSSL およびシステム CA 証明書がインストールされていないホストにデプロイする場合、New Relic サーバーへの接続で問題が発生し、APM データが失われる可能性があります。

Solution: New Relic サーバーには、正常な接続を開始するために CA 証明書を使用する HTTPS が必要です。これらは、ホストに応じてさまざまな方法でインストールできます。以下は、ホストの準備状況をテストし、CA 証明書をインストールするための役立つリンクです。

必要に応じて、構成を介して CA バンドルファイルへのパスを指定することにより、任意の CA バンドルを使用するようにエージェントを構成できます: :ca_bundle_path 。詳細については、Ruby のカスタム SSL 証明書を参照してください。

非推奨の API と構成属性

すべての非推奨の API には、範囲を拡張したり、非推奨の API の堅牢性を向上させたりする代替 API があります。

拒否リストと許可リストの有効化

Potential issue: ブラック/ホワイトリストの属性は機能しなくなりました。

Solution : 構成または環境変数設定で、 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

アクティブレコード

Potential issue: 古いバージョンの Active Record を無効にすることは機能しなくなりました。

Solution: 次の構成設定を変更します。

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

httpResponseCode

Potential issue: 属性httpResponseCodeは、報告されたトレースの UI に表示されなくなりました。

Solution: httpResponseCode http.statusCodeに置き換えられました。

通知エラー（trace_only）

Potential issue: :trace_onlyオプションをNewRelic::Agent.notice_errorに渡すことは機能しなくなりました。

Solution: :trace_onlyを:expected属性に置き換えます。

分散型トレーシングAPI

Potential issue: API メソッドcreate_distributed_trace_payloadおよびaccept_distributed_trace_payloadを呼び出すときに、アプリケーションコードでエラーが発生します。

Solution: 代わりに、それぞれinsert_distributed_trace_headersとaccept_distributed_trace_headersを参照してください。