Ruby デバッガーの仕組み: TracePoint、命令列、CRuby API
Ruby 開発者の皆さん、こんにちは！
デバッグはソフトウェア開発における重要な工程ですが、ほとんどの開発者は実際のデバッグの仕組みを理解せずにデバッガーを使用しています。RubyMine チームは数年にわたって Ruby 用のデバッグツールを開発しており、その開発の行程で得た知見の一部を共有したいと考えています。
この記事では、Ruby デバッガーの背後にある TracePoint、命令列、および Ruby の C レベルデバッグ API という主な技術について説明します。
まずは TracePoint について取り上げ、それを使用してデバッガーに重要なイベントでコードを停止させる仕組みを見てみましょう。その後、最小限の機能を備えたデバッガーを構築して実際の動作を確認します。次に、Ruby のバイトコード概要とその TracePoint との連携の仕組みを理解するため、命令列について取り上げます。最後に、Ruby の C レベル API とそのメリットについて簡単に説明します。
このブログ記事は、EuRuKo 2024 と RubyKaigi 2025 で RubyMine のチームリーダーである Dmitry Pogrebnoy が講演した「Demystifying Debuggers」に基づく連載の第 2 部です。最初の記事をまだご覧になっていない方は、こちらを先にお読みいただくことをお勧めします。動画をご希望ですか？元の講演は、こちらからご視聴いただけます。
準備はできましたか？では、始めましょう！
Ruby デバッガーの背後にあるコア技術
デバッガーの内部を詳しく見る前に、Ruby デバッガーを実現している TracePoint と命令列という 2 つのコア技術を理解しておく必要があります。使用するデバッガーを問わず、どれも Ruby 自体に組み込まれたこれらの基本機能を使用しています。次のセクションでは、各技術の仕組みとその重要性について説明します。
TracePoint: コード実行へのフック
まずは TracePoint から説明します。これは 2013 年に Ruby 2.0 で導入された強力なインストルメンテーション技術であり、メソッドの呼び出し、行の実行、または例外の発生などの特定の実行時イベントをインターセプトし、これらのイベントが発生した際にカスタムコードを実行することで機能します。TracePoint はほぼすべての Ruby コンテキストで機能し、スレッドとファイバーとうまく連携します。ただし、現時点では Ractor のサポートに制限があります。
例を見ながら TracePoint の機能を確認してみましょう。
def say_hello
puts "Hello Ruby developers!"
end
TracePoint.new(:call) do |tp|
puts "Calling method '#{tp.method_id}'"
end.enable
say_hello
# => Calling method 'say_hello'
# => Hello Ruby developers!
この例には、puts ステートメントを含む単純な say_hello メソッドと、call 型のイベントをウォッチする TracePoint が含まれています。TracePoint の中では、method_id を使用して呼び出し対象のメソッドの名前を出力しています。コメントの出力を見ると、say_hello メソッドに入る際に TracePoint がトリガーされており、それが完了して初めてメソッド自体が実際のメッセージを出力していることが分かります。
この例は、TracePoint を使用して普通のコードの実行を特別なイベントが発生する特定のポイントでインターセプトし、独自のカスタムコードを実行できることを示しています。ブレークポイントでデバッガーが停止するたびに、TracePoint が処理を担います。この技術はデバッグ以外にも役立つため、パフォーマンスの監視、ログの記録、さらには実行時の挙動に関する知見を得たり、プログラムの動作に影響を与えたりする必要があるその他の場面でも使用されます。
TracePoint を使用したごく単純な Ruby デバッガーの構築
TracePoint の技術のみを使用し、可能な限り単純な Ruby デバッガーを構築してみましょう。
def say_hello
puts "Hello Ruby developers!"
end
TracePoint.new(:call) do |tp|
puts "Call method '#{tp.method_id}'"
while (input = gets.chomp) != "cont"
puts eval(input)
end
end.enable
say_hello
これは TracePoint の例とほぼ同じコードですが、今回は <0>TracePoint コードの本文が若干変更されています。
その挙動を詳しく見てみましょう。TracePoint ブロックは gets.chomp 経由でユーザーの入力を受け付けており、その入力を現在のコンテキスト内で eval メソッドを使用して評価し、その結果を puts で出力しています。本当にそれだけのことです。たった数行のコードで単純明快かつ効果的なデバッグの仕組みが構築されています。
これにより、各メソッドの呼び出しで現在のプログラムコンテキストをイントロスペクトし、必要に応じて状態を変更するというデバッガーのコア機能の 1 つが実現されています。たとえば、新しい Ruby 定数の定義、その場でのクラスの作成、実行中の変数の値変更などが可能です。簡単で強力な仕組みだと思いませんか？ぜひ実行してみてください！
ただ、これが完成形のデバッガーでないことは明らかです。例外処理やその他多くの基本機能が欠落しています。しかし、それ以外の要素を無視して骨組みだけを見てみると、これがすべての Ruby デバッガーの基礎となる基本的な仕組みであることがわかります。
この単純な例は、TracePoint が Ruby デバッガーの基礎として機能することを示しています。TracePoint の技術がなければ、モダンな Ruby デバッガーの構築は不可能だったことでしょう。
命令列: Ruby のバイトコードの解明
Ruby デバッガーのもう 1 つの重要な技術は命令列です。
命令列（短縮形は iseq）は、Ruby 仮想マシンが実行するコンパイル済みのバイトコードを表します。これは Ruby の「アセンブリ言語」（バイトコードにコンパイルした後の Ruby コードの低位表現）だと考えることができます。命令列は Ruby VM の内部動作に緊密に結び付いているため、Ruby のバージョンが異なれば、同じ Ruby コードでも命令の観点だけでなく、全体的な構造や異なる命令列間の関係においても異なる iseq が生成される場合があります。
命令列により、Ruby コードの低位表現に直接アクセスすることができます。デバッガーは特定の内部フラグを切り替えたり、 iseq 内の命令を変更したりすることでこの機能を活用し、実行時に元のソースコードを変更することなくプログラムの実行方法を効果的に変更することができます。
たとえば、デバッガーがデフォルトではトレースイベントがない特定の命令でトレースイベントを有効にすると、そのポイントに到達した時点で Ruby VM が一時停止する場合があります。これは、特定の言語構造と呼び出しのステップ実行チェーンにおけるブレークポイントの動作です。開発者がデバッグステートメントを挿入したり、何らかの方法でコードを変更したりすることなく透明的に動作するデバッガーを構築するには、バイトコードを直接インストルメント化する機能が不可欠です。
Ruby コードで命令列を取得する方法を見てみましょう。
def say_hello puts "Hello Ruby developers 💎!" end method_object = method(:say_hello) iseq = RubyVM::InstructionSequence.of(method_object) puts iseq.disasm
このコードをさらに詳しく調べてみましょう。まず、先述の puts ステートメントを含む <0>say_hello メソッドがあります。次に method(:say_hello) を使用し、そのメソッドからメソッドオブジェクトを作成しています。最後に disasm を使用し、そのメソッドの命令列を取得して人間が読み取れる形式で出力しています。これにより、内部動作を調査し、Ruby が実行する実際のバイトコード命令を確認できるようになります。
出力を調査し、どのように表示されるのか見てみましょう。
== disasm: #<ISeq:say_hello@iseq_example.rb:1 (1,0)-(3,3)> 0000 putself ( 2)[LiCa] 0001 putchilledstring "Hello Ruby developers 💎!" 0003 opt_send_without_block <calldata!mid:puts, argc:1, FCALL|ARGS_SIMPLE> 0005 leave ( 3)[Re]
最初の行に Ruby エンティティに関するメタデータが表示されています。具体的には、(1,0)-(3,3) の位置範囲で iseq_example.rb に say_hello メソッドが定義されているという情報です。その下には、Ruby VM が実行する実際の命令があります。各行は 1 つの命令を表しており、人間が読み取れる形式で表示されています。「Hello Ruby developers 💎!」文字列引数はソースコード内の記述内容が維持されているため、簡単に読み取れます。複雑なエンコーディングやコーディングも、非 ASCII 文字列もありません。このような透明性により、バイトコードレベルでの挙動をより簡単に理解できるようになります。
命令列はバイトコード内の重要な実行ポイントをマークすることで、Ruby のデバッグにおいて重要な役割を果たしています。出力内の角括弧表記では、行イベントの Li やメソッド呼び出しの Ca、そして返却処理の Re といったマーカーが示されています。これらのマーカーは、Ruby VM に実行時イベントを発動させるべきタイミングを指示しています。TracePoint はこれらのマーカーを参照して実行中のプログラムにフックします。これらのイベントをリッスンし、イベントが発生する際に介入するのです。2 つの技術がこのように緊密に結び付いていることで、デバッガーが実行を一時停止し、状態を検査することが可能になっています。
さらに踏み込む: Ruby の C レベルデバッグ API
ここまでで、Ruby デバッガーの背後にある TracePoint と命令列という 2 つのコア技術を説明してきました。実用的な Ruby デバッガーを構築するにはこれらだけでも十分ですが、RubyMine が提供する高度な機能（スマートステップ実行やコールスタック内の前後移動など）を実装する場合は、TracePoint と命令列だけでは不可能です。そのような機能をサポートするには、もう一段階踏み込み、Ruby 自体が提供する低レベルのデバッグ API を活用する必要があります。
CRuby は、一般公開されている Ruby API によって残されたギャップを埋める多数の内部メソッドを公開しています。そのようなメソッドには、vm_core.h、vm_callinfo.h、iseq.h、debug.h などの C ヘッダーに定義されているものがあります。これらの内部インターフェースにより、一般公開の API の対応範囲を超える強力な機能を利用できるようになりますが、重要なトレードオフが伴います。
これらは CRuby に特化しているため、これらを使用するデバッガーは JRuby や TruffleRuby などの他の実装では機能しません。これらの API は、すべての Ruby バージョンで公開版でも安定版でもないという欠点もあります。些細な更新でも機能しなくなる可能性があるため、これらのメソッドを利用しているデバッガーは Ruby の変更に対応できるように常に注意しておく必要があります。しかし、この低位 API がどのようなもので、デバッガーツールに何を提供するのかを把握しておくため、このような内部メソッドをいくつか調査する価値はあります。
rb_tracepoint_new(…) から始めましょう。
VALUE rb_tracepoint_new(VALUE target_thread_not_supported_yet, rb_event_flag_t events, void (*func)(VALUE, void *), void *data);
このメソッドは Ruby コードにトレースポイントを作成するのと同じように機能しますが、より柔軟性が高く、高度な用途に使用できます。Ruby VM により深くアクセスする必要のある C 拡張機能として作成された低レベルのデバッガーでは特に役立ちます。RubyMine デバッガーではこのアプローチを採用することで、トレースポイントを有効/無効化するタイミングと場所をより正確にコントロールできるようにしています。これはスマートステップ実行の実装に不可欠なものです。
rb_debug_inspector_open(…) という便利なメソッドもあります。
VALUE rb_debug_inspector_open(rb_debug_inspector_func_t func, void *data);
この C レベルの API では、VM の状態を変更せずにコールスタックを調査できます。func コールバックは、バインディング、位置、命令列、およびその他のフレームの詳細を提供する rb_debug_inspector_t 構造体を受け取ります。RubyMine デバッガーでは、プログラムがデバッガーによって中断された際にフレームのリストを取得し、コールスタック上でフレームを切り替える機能を実装するために使用されています。この API がない場合、Ruby でのフレーム内の移動操作とカスタムフレームの検査はかなり困難になるでしょう。
最後の例は、iseq オブジェクトと連携するメソッドのペアです。rb_iseqw_to_iseq(…) メソッドは Ruby の値から C の値に iseq を変換するのに対し、rb_iseq_original_iseq(…) メソッドは C から Ruby に変換します。これらのメソッドを使用することで、Ruby デバッガーは正確な低レベルの制御が必要な場合に Ruby コードと C 拡張機能コード間を切り替えています。RubyMine デバッガーでは、これらはスマートステップ実行の実装で活発に使用されており、どのコードがデバッグ中にステップインされるべきかを判断する上で役立っています。
これらの低レベルの API は、TracePoint と命令列だけでは不可能な高度なデバッグ機能の構築に使用できる強力なツールを提供します。ただし、これらにはコストが伴います。プラットフォームが CRuby に固定され、複数の Ruby バージョン間で動作が不安定になるために保守の負担が大きくなるのです。とはいえ、Ruby VM との緊密な統合を必要とするデバッガーでは、これらは依然として不可欠なものです。
まとめ
この記事では、Ruby デバッガーを強力にする TracePoint と命令列と言う基本技術を説明しました。これらの 2 つのコンポーネントは、モダンな Ruby デバッガーが実行中の Ruby コードをどのように観測し、対話するかの基礎を形成するものです。TracePoint はメソッドの呼び出しや行の実行といった特定の実行時イベントへのフックを可能にするのに対し、命令列ではコンパイル済みの Ruby VM バイトコードへの低レベルアクセスを得られます。
また、低レベルの CRuby C API によってコード実行をさらに正確に制御する方法についても簡単に説明し、RubyMine などのデバッガーが高度な機能をどのように実装しているかについての理解を深めました。ここでは完全なデバッガーの実装については説明しませんでしたが、この基礎はこれらのツールの動作を理解するための基盤となります。
今後の記事では、モダンなデバッガーがこの基盤の上にどのように構築されているかをさらに詳しく説明します。
コーディングをお楽しみください。バグが少なく、簡単に修正できることを願っています！
RubyMine チーム一同より
Subscribe to RubyMine Blog updates
