{"id":16643456,"url":"https://github.com/sonots/gdbdump-ruby","last_synced_at":"2025-03-21T15:32:35.543Z","repository":{"id":56873681,"uuid":"92902502","full_name":"sonots/gdbdump-ruby","owner":"sonots","description":"Dump C level and Ruby level backtrace from living ruby process or core file using gdb","archived":false,"fork":false,"pushed_at":"2018-06-20T18:32:51.000Z","size":41,"stargazers_count":15,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-14T23:14:23.997Z","etag":null,"topics":["backtrace","gdb","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sonots.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-31T03:58:11.000Z","updated_at":"2022-07-07T19:37:57.000Z","dependencies_parsed_at":"2022-08-20T22:30:24.819Z","dependency_job_id":null,"html_url":"https://github.com/sonots/gdbdump-ruby","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fgdbdump-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fgdbdump-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fgdbdump-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonots%2Fgdbdump-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sonots","download_url":"https://codeload.github.com/sonots/gdbdump-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244822743,"owners_count":20516158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backtrace","gdb","ruby"],"created_at":"2024-10-12T08:08:38.143Z","updated_at":"2025-03-21T15:32:35.264Z","avatar_url":"https://github.com/sonots.png","language":"Ruby","readme":"# gdbdump\n\nDump C level and Ruby level backtrace from living ruby process or core file using gdb.\n\n## Installation\n\n```\n$ gem install gdbdump\n```\n\n## Requirements\n\n* gdb\n* linux\n* `sudo gdb` must be allowed to dump backtrace of living ruby process\n\nIt was verified that gdbdump works with ruby executables built by [rbenv/ruby-build](https://github.com/rbenv/ruby-build).\n\n## Usage\n\n```\nUsage: gdbdump [options] [ pid | /path/to/ruby pid | /path/to/ruby core ]\n    -d, --[no-]debug                 print debug log (default: false)\n    -x, --gdbinit FILE               path to ruby repo's .gdbinit (default: some of ruby repo's .gdbinit is pre-bundle in this gem)\n        --gdb PATH                   path to gdb command (default: gdb)\n```\n\n### --gdbinit\n\nDefault supported ruby versions: 2.1.x - 2.4.x\n\nRuby repo's [.gdbinit](https://github.com/ruby/ruby/blob/trunk/.gdbinit) file defines useful helper functions and it is maintained by ruby core team. `gdbdump` uses it. `.gdbinit` of some versions written on above are pre-bundled in this gem. But, if you want to use `gdbdump` for older or newer ruby versions:\n\n1. Download .gdbinit from ruby repo like [ruby/2.4.1/.gdbinit](https://github.com/ruby/ruby/blob/v2_4_1/.gdbinit), and specify with `-x` option\n2. Or, send PR to bundle the .gdbinit in `gdbdump` gem.\n\n## Example (live ruby process)\n\nWith live ruby process of pid 1897,\n\n```\n$ gdbdump 1897\n```\n\nYou will see C and Ruby level backtrace as:\n\n```\n$1 = (rb_vm_t *) 0x7f46bb071f20\n* #\u003cThread:0x7f46bb0a5ee8 rb_thread_t:0x7f46bb0725d0 native_thread:0x7f46ba514740\u003e\n0x7f46ba16d700 \u003cthread_join_m at thread.c:980\u003e:in `join'\nloop.rb:17:in `\u003cmain\u003e'\n* #\u003cThread:0x7f46bb202750 rb_thread_t:0x7f46bb3e03d0 native_thread:0x7f46b89c0700\u003e\n0x7f46ba0e4f30 \u003crb_f_sleep at process.c:4388\u003e:in `sleep'\nloop.rb:6:in `block (2 levels) in \u003cmain\u003e'\n0x7f46ba1a72b0 \u003crb_f_loop at vm_eval.c:1137\u003e:in `loop'\nloop.rb:4:in `block in \u003cmain\u003e'\n* #\u003cThread:0x7f46bb202660 rb_thread_t:0x7f46bb3e47e0 native_thread:0x7f46b87be700\u003e\n0x7f46ba0e4f30 \u003crb_f_sleep at process.c:4388\u003e:in `sleep'\nloop.rb:13:in `block (2 levels) in \u003cmain\u003e'\n0x7f46ba1a72b0 \u003crb_f_loop at vm_eval.c:1137\u003e:in `loop'\nloop.rb:11:in `block in \u003cmain\u003e'\n```\n\n## Example (core file)\n\nWith core file, you have to specify path of ruby executable.\n\n```\n$ gdbdump $HOME/.rbenv/versions/2.4.1/bin/ruby core.1897\n```\n\nYou can get a core file with `gcore` command as:\n\n```\n$ sudo gcore 1897\n```\n\n## FAQ\n\n* Q. How this work?\n  * A. Attach to the ruby process with gdb, and call `rb_ps` defined in gdbinit. That's it.\n* Q. Is this available for production process?\n  * A. GDB stops the process during printing backtrace, would cause some issues\n\n## Comparisons\n\n* gdb\n  * You can print C level backtrace with raw gdb, of course\n* [sigdump](https://github.com/frsyuki/sigdump)\n  * sigdump enables to print ruby level backtrace with sending CONT signal to living ruby process.\n  * The ruby process **must pre-install** `sigdump` gem and `require 'sigdump/setup'` unlike gdbdump.\n  * sigdump prints backtrace in signal handler, so blocks main thread, but other threads still work unlike gdbdump.\n* [gdbruby](https://github.com/gunyarakun/gdbruby)\n  * gdbruby enables to print C level and ruby level backtrace of living ruby process and core file.\n  * gdbruby **must follow changes of C level interfaces of CRuby** to get backtrace of the core file, it rises fragility that it will be broken on newer ruby versions.\n  * gdbruby supports only ruby 2.0 and 2.1 (2017-06-05).\n  * I believe `gdbdump` can replace `gdbruby`.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n### Investigation\n\nBelows are my investigation notes about how to print C level and Ruby level backtrace via gdb.\n\n#### (1) rb_print_backtrace() and rb_backtrace()\n\nCRuby itself has [rb_print_backtrace](https://github.com/ruby/ruby/blob/26864584d269b6141a27c783cf8b751c067c7dbe/vm_dump.c#L671) function to print C level backtrace, and [rb_backtrace](https://github.com/ruby/ruby/blob/eb59047e2aabb050b23061d513f7b89dc2905670/vm_backtrace.c#L770) function to print Ruby level backtrace.\nI first tried to use them.\n\nHowever, they print a backtrace of only current thread. Furthermore, rb_print_backtrace supports printing outputs to only STDERR.\nAlso, because it calls C function, it works only for a living process, and does not work for *core* file.\n\n```ruby\ndef print_backtrace\n  run do |gdb|\n    gdb.cmd_exec('call write(2, \"== c backtrace ==\\n\", 18)')\n    gdb.cmd_exec('call rb_print_backtrace()')\n    gdb.cmd_exec('call write(2, \"== ruby backtrace ==\\n\", 21)')\n    gdb.cmd_exec('call rb_backtrace()')\n  end\nend\n```\n\n#### (2) bt and rb_eval_string()\n\nI secondly tried to use GDB's `info threads` and `bt` command to print C level backtrace. This was fine.\n\nI also tried to print Ruby level backtrace by calling [rb_eval_string](https://github.com/ruby/ruby/blob/44396dbe123511678710cfb21223c954b9ceaafb/vm_eval.c#L1474) with Ruby codes as:\n\n```ruby\ndef ruby_backtrace_code\n  code = +%Q[File.open('#{dumpfile}', 'a') {|f|]\n  code \u003c\u003c %q[\n    Thread.list.each {|th|\n      f.write %Q[  Thread #{th} status=#{th.status} priority=#{th.priority}\\n]\n      th.backtrace.each {|bt|\n        f.write %Q[      #{bt}\\n]\n      }\n    }\n  }]\n  code.split(\"\\n\").map(\u0026:strip).join('; ')\nend\n\ndef print_backtrace\n  run do |gdb|\n    gdb.cmd_exec(%Q[call rb_eval_string(\"#{ruby_backtrace_code}\")])\n  end\nend\n```\n\nHowever, the debugee (target) process got stuck after `call rb_eval_string`. It seemed the ruby process will be broken if ruby codes are executed via gdb.\n\n#### (3) rb_ps from ruby trunk's .gdbinit\n\nI thirdly tried to use `rb_ps` function defined in [.gdbinit](https://github.com/ruby/ruby/blob/44396dbe123511678710cfb21223c954b9ceaafb/.gdbinit#L983) of ruby repository to print C level and Ruby level backtrace of all threads.\n\nSince `.gdbinit` is maintained by ruby core team, I do not need to follow changes of C level interfaces of CRuby as long as I follow `.gdbinit`.\n\nBecause `rb_ps` does not call any C functions inside, it can print C and Ruby level backtrace for *core* file.\n\nThe drawback of this way is that\n\n1. I have to follow changes of `.gdbinit` in newer ruby versions\n2. `rb_ps` takes somewhat long time like 2.6 seconds to print backtrace.\n\nCurrently, I am taking this way.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/sonots/gdbdump. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Gdbdump project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/gdbdump/blob/master/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonots%2Fgdbdump-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsonots%2Fgdbdump-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonots%2Fgdbdump-ruby/lists"}