search

ionelmc / python-manhole

Debugging manhole for python applications.
https://pypi.python.org/pypi/manhole
BSD 2-Clause "Simplified" License
374 stars 24 forks source link
debugging python

readme

======== Overview

.. start-badges

.. list-table:: :stub-columns: 1

* - docs
  - |docs|
* - tests
  - |github-actions| |coveralls| |codecov|
* - package
  - |version| |wheel| |supported-versions| |supported-implementations| |commits-since|

.. |docs| image:: https://readthedocs.org/projects/python-manhole/badge/?style=flat :target: https://readthedocs.org/projects/python-manhole/ :alt: Documentation Status

.. |github-actions| image:: https://github.com/ionelmc/python-manhole/actions/workflows/github-actions.yml/badge.svg :alt: GitHub Actions Build Status :target: https://github.com/ionelmc/python-manhole/actions

.. |coveralls| image:: https://coveralls.io/repos/github/ionelmc/python-manhole/badge.svg?branch=master :alt: Coverage Status :target: https://coveralls.io/github/ionelmc/python-manhole?branch=master

.. |codecov| image:: https://codecov.io/gh/ionelmc/python-manhole/branch/master/graphs/badge.svg?branch=master :alt: Coverage Status :target: https://app.codecov.io/github/ionelmc/python-manhole

.. |version| image:: https://img.shields.io/pypi/v/manhole.svg :alt: PyPI Package latest release :target: https://pypi.org/project/manhole

.. |wheel| image:: https://img.shields.io/pypi/wheel/manhole.svg :alt: PyPI Wheel :target: https://pypi.org/project/manhole

.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/manhole.svg :alt: Supported versions :target: https://pypi.org/project/manhole

.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/manhole.svg :alt: Supported implementations :target: https://pypi.org/project/manhole

.. |commits-since| image:: https://img.shields.io/github/commits-since/ionelmc/python-manhole/v1.8.1.svg :alt: Commits since latest release :target: https://github.com/ionelmc/python-manhole/compare/v1.8.1...master

.. end-badges

Manhole is in-process service that will accept unix domain socket connections and present the stacktraces for all threads and an interactive prompt. It can either work as a python daemon thread waiting for connections at all times or a signal handler (stopping your application and waiting for a connection).

Access to the socket is restricted to the application's effective user id or root.

This is just like Twisted's manhole <http://twistedmatrix.com/documents/current/api/twisted.conch.manhole.html>__. It's simpler (no dependencies), it only runs on Unix domain sockets (in contrast to Twisted's manhole which can run on telnet or ssh) and it integrates well with various types of applications.

:Documentation: http://python-manhole.readthedocs.org/en/latest/

Usage

Install it::

pip install manhole

You can put this in your django settings, wsgi app file, some module that's always imported early etc:

.. code-block:: python

import manhole
manhole.install() # this will start the daemon thread

# and now you start your app, eg: server.serve_forever()

Now in a shell you can do either of these::

netcat -U /tmp/manhole-1234
socat - unix-connect:/tmp/manhole-1234
socat readline unix-connect:/tmp/manhole-1234

Socat with readline is best (history, editing etc). If your socat doesn't have readline try this <https://launchpad.net/~ionel-mc/+archive/ubuntu/socat>_.

Sample output::

$ nc -U /tmp/manhole-1234

Python 2.7.3 (default, Apr 10 2013, 06:20:15)
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> dir()
['__builtins__', 'dump_stacktraces', 'os', 'socket', 'sys', 'traceback']
>>> print 'foobar'
foobar

Alternative client

There's a new experimental manhole-cli bin since 1.1.0, that emulates socat::

usage: manhole-cli [-h] [-t TIMEOUT] [-1 | -2 | -s SIGNAL] PID

Connect to a manhole.

positional arguments:
  PID                   A numerical process id, or a path in the form:
                        /tmp/manhole-1234

optional arguments:
  -h, --help            show this help message and exit
  -t TIMEOUT, --timeout TIMEOUT
                        Timeout to use. Default: 1 seconds.
  -1, -USR1             Send USR1 (10) to the process before connecting.
  -2, -USR2             Send USR2 (12) to the process before connecting.
  -s SIGNAL, --signal SIGNAL
                        Send the given SIGNAL to the process before
                        connecting.

.. end-badges

Features

Options

.. code-block:: python

manhole.install(
    verbose=True,
    verbose_destination=2,
    patch_fork=True,
    activate_on=None,
    oneshot_on=None,
    sigmask=manhole.ALL_SIGNALS,
    socket_path=None,
    reinstall_delay=0.5,
    locals=None,
    strict=True,
)

Environment variable installation

Manhole can be installed via the PYTHONMANHOLE environment variable.

This::

PYTHONMANHOLE='' python yourapp.py

Is equivalent to having this in yourapp.py::

import manhole
manhole.install()

Any extra text in the environment variable is passed to manhole.install(). Example::

PYTHONMANHOLE='oneshot_on="USR2"' python yourapp.py

What happens when you actually connect to the socket

  1. Credentials are checked (if it's same user or root)
  2. sys.__std*__/sys.std* are redirected to the UDS
  3. Stacktraces for each thread are written to the UDS
  4. REPL is started so you can fiddle with the process

Known issues

SIGTERM and socket cleanup

By default Python doesn't call the atexit callbacks with the default SIGTERM handling. This makes manhole leave stray socket files around. If this is undesirable you should install a custom SIGTERM handler so atexit is properly invoked.

Example:

.. code-block:: python

import signal
import sys

def handle_sigterm(signo, frame):
    sys.exit(128 + signo)  # this will raise SystemExit and cause atexit to be called

signal.signal(signal.SIGTERM, handle_sigterm)

Using Manhole with uWSGI

Because uWSGI overrides signal handling Manhole is a bit more tricky to setup. One way is to use "uWSGI signals" (not the POSIX signals) and have the workers check a file for the pid you want to open the Manhole in.

Stick something this in your WSGI application file:

.. sourcecode:: python

from __future__ import print_function
import sys
import os
import manhole

stack_dump_file = '/tmp/manhole-pid'
uwsgi_signal_number = 17

try:
    import uwsgi

    if not os.path.exists(stack_dump_file):
        open(stack_dump_file, 'w')

    def open_manhole(dummy_signum):
        with open(stack_dump_file, 'r') as fh:
            pid = fh.read().strip()
            if pid == str(os.getpid()):
                inst = manhole.install(strict=False, thread=False)
                inst.handle_oneshot(dummy_signum, dummy_signum)

    uwsgi.register_signal(uwsgi_signal_number, 'workers', open_manhole)
    uwsgi.add_file_monitor(uwsgi_signal_number, stack_dump_file)

    print("Listening for stack mahole requests via %r" % (stack_dump_file,), file=sys.stderr)
except ImportError:
    print("Not running under uwsgi; unable to configure manhole trigger", file=sys.stderr)
except IOError:
    print("IOError creating manhole trigger %r" % (stack_dump_file,), file=sys.stderr)

# somewhere bellow you'd have something like
from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()
# or
def application(environ, start_response):
    start_response('200 OK', [('Content-Type', 'text/plain'), ('Content-Length', '2')])
    yield b'OK'

To open the Manhole just run echo 1234 > /tmp/manhole-pid and then manhole-cli 1234.

Requirements

:OS: Linux, OS X :Runtime: Python 2.7, 3.4, 3.5, 3.6 or PyPy

Similar projects