DebugSocket

A unix domain socket that listens for debug commands.

Warning

Anything sent to the unix domain socket will be passed to eval(). Be careful. Security-wise, this is OK: the debug socket is restricted to the process owner. The socket permissions are 0600, so only the user running the process can connect to the socket. The user that is running the process can also attach GDB to the running process and do the same things the socket allows, only it won't be memory safe ;).

Usage

A rails example with puma and sidekiq:

in config/puma.rb

on_worker_boot do
  DebugSocket.logger = Rails.logger
  DebugSocket.start(Rails.root.join("tmp", "puma-debug-#{Process.pid}.sock"))
end

on_worker_shutdown do
  DebugSocket.stop
end

in config/initializers/sidekiq.rb

Sidekiq.configure_server do |_config|
  DebugSocket.logger = Sidekiq::Logging.logger
  # GOTCHA: if the Rails.root.join("tmp", "sidekiq-debug-#{Process.pid}.sock")
  # path is too long, this will fail. The max on Linux is 108 characters, MacOS
  # is 104. If the path is too long, try using a relative path or /tmp/<blah>.
  DebugSocket.start(Rails.root.join("tmp", "sidekiq-debug-#{Process.pid}.sock"))
  at_exit { DebugSocket.stop }
end

You can now send ruby instruction commands through the socket and they'll be executed in your running process. You can use socat to write and read from the socket and dump to stdout like so:

% echo backtrace | socat - UNIX-CONNECT:~/tmp/puma-debug-1234.sock
2016-08-09T00:51:57Z puma: cluster worker 0: 1234
2016-08-09T00:51:57Z pid=1234 thread.object_id=70099243629020 thread.status=run
lib/debug_socket.rb:55:in `backtrace'
lib/debug_socket.rb:55:in `block in backtrace'
lib/debug_socket.rb:54:in `map'
lib/debug_socket.rb:54:in `backtrace'
spec/debug_socket_spec.rb:48:in `block (3 levels) in <top (required)>'

2016-08-09T00:51:57Z pid=1234 thread.object_id=70121809360520 thread.status=sleep
spec/debug_socket_spec.rb:48:in `sleep'
spec/debug_socket_spec.rb:48:in `block (4 levels) in <top (required)>'

The gem also provides a script. The debug-socket script takes one argument, the path to the unix socket, and it will run the backtrace command through that socket.

% debug-socket ~/tmp/puma-debug-1234.sock
2016-08-09T00:51:57Z puma: cluster worker 0: 1234
2016-08-09T00:51:57Z pid=1234 thread.object_id=70099243629020 thread.status=run
lib/debug_socket.rb:55:in `backtrace'
lib/debug_socket.rb:55:in `block in backtrace'
lib/debug_socket.rb:54:in `map'
lib/debug_socket.rb:54:in `backtrace'
spec/debug_socket_spec.rb:48:in `block (3 levels) in <top (required)>'

2016-08-09T00:51:57Z pid=1234 thread.object_id=70121809360520 thread.status=sleep
spec/debug_socket_spec.rb:48:in `sleep'
spec/debug_socket_spec.rb:48:in `block (4 levels) in <top (required)>'

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/square/debug_socket.

If you would like to contribute code to DebugSocket, thank you! You can do so through GitHub by forking the repository and sending a pull request. However, before your code can be accepted into the project we need you to sign Square's (super simple) Individual Contributor License Agreement (CLA)

License

Copyright 2016 Square, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.