Metadata-Version: 2.1
Name: tipper
Version: 0.1
Summary: A utility for dumping stack traces of running Python processes
Home-page: http://bitheap.org/tipper/
Download-URL: http://bitheap.org/tipper/tipper-0.1.tar.gz
Author: Brodie Rao
Author-email: brodie@bitheap.org
License: MIT
Keywords: daemon debugging django process server traceback
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Utilities

========
 Tipper
========

Tipper is a small utility for dumping `stack tracebacks`_ of running
Python processes.

Included is a module that, when imported, installs a `signal handler`_
for `SIGUSR1`_. Running ``kill -SIGUSR1 [pid]`` will cause the process
to dump the current stack trace of each thread to
``$TMPDIR/tipper-[unix timestamp]-[parent pid]-[pid].log``.

Tipper can also be used as `Django`_ application, though it has no
dependencies on Django itself.

Python 2.5 or newer is required. Python 3.x is also supported.

.. _stack tracebacks: http://docs.python.org/library/traceback.html
.. _signal handler: http://docs.python.org/library/signal.html
.. _SIGUSR1: http://en.wikipedia.org/wiki/SIGUSR1_and_SIGUSR2
.. _Django: http://www.djangoproject.com/


Download
--------

* tipper-0.1.tar.gz_ (4 KB, requires Python 2.5-2.7 or Python 3.1)

.. _tipper-0.1.tar.gz: http://bitheap.org/tipper/tipper-0.1.tar.gz


Usage
-----

To take Tipper for a test drive, first install Tipper::

    $ pip install tipper

Set up a Python process to inspect::

    $ cat > test.py <<EOF
    > import os, sys, time, tipper
    > sys.stdout.write('%s\n' % os.getpid())
    > while True:
    >     time.sleep(1)
    > EOF
    $ python test.py
    945

And send ``SIGUSR1`` to it::

    $ kill -SIGUSR1 945

You should end up with a file in ``$TMPDIR`` that looks like the following::

    $ cat "$TMPDIR/tipper-1292830152.19-681-945.log"
    Date: 2010-12-20 18:29:12.192733
    Parent process ID: 681
    Process ID: 945

    Traceback (thread 140048470763264):

      File "test.py", line 4, in <module>
        time.sleep(1)

          Arguments: <module>()
          Local variables:

          {'__builtins__': <module '__builtin__' (built-in)>,
           '__doc__': None,
           '__file__': 'test.py',
           '__name__': '__main__',
           '__package__': None,
           'os': <module 'os' from '/usr/lib/python2.6/os.pyc'>,
           'sys': <module 'sys' (built-in)>,
           'time': <module 'time' (built-in)>,
           'tipper': <module 'tipper' from '/usr/local/lib/python2.6/dist-packages/tipper/__init__.py'>}

To get a briefer overview of the log, you can use grep::

    $ grep -v '^      \|^$' "$TMPDIR/tipper-1292830152.19-681-945.log"
    Date: 2010-12-20 18:29:12.192733
    Parent process ID: 681
    Process ID: 945
    Traceback (thread 140048470763264):
      File "test.py", line 4, in <module>
        time.sleep(1)


News
----

Version 0.1 (Dec. 20, 2010)
```````````````````````````
* Initial release.


Development
-----------

Download the official development repository using Mercurial_::

    hg clone https://bitbucket.org/brodie/tipper

Visit Bitbucket_ if you'd like to fork the project, watch for new
changes, or report issues.

.. _Mercurial: http://mercurial.selenic.com/
.. _Bitbucket: https://bitbucket.org/brodie/tipper
