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.

潜在的な問題： エージェントが初期化されず、データの報告を開始できません。ログにスタックレベルが深すぎるというエラーメッセージが報告されます。

解決策:構成と依存関係の検出メカニズムは、構成を通じて制御できるようになりました。デフォルトでは、すべての自動計測された gem/libraries は prepend 戦略でアクティブ化されます。構成ファイルに設定が表示されない場合のこれらのライブラリのデフォルトの構成設定はautoであり、これが最適な戦略を選択します。prepend 戦略との既知の競合の場合、 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 をご覧ください。

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

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

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

非推奨の API と構成属性

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

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

潜在的な問題： Black/White のリストの属性が機能しなくなった。

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

潜在的な問題:報告されたトレースの UI に属性httpResponseCodeが表示されなくなりました。

解決策: 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を参照してください。