                                    --------
                                    Mongoose
                                    --------



Description
===============================================================================
    
    Mongoose - catches runaway Pythons
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    This package provides functionality to catch and report otherwise
    unhandled Python exceptions in a helpful and extensible manner. It is
    intended for use in deployed production or beta software to provide a
    graceful exit and report should an uncaught exception occur.
    
    When an uncaught exception occurs one or more "reporters" can act
    on the event. Supplied sample reporters log the event to a file,
    email the developer or support staff, display output on a console
    and display a wxWindows dialog to the user.
    
    Includes "Mongoose Incident Identifier(TM)" technology to provide
    developers with a convenient way to track the same exceptional incident
    (i.e. "bug") on multiple computers. A Mongoose Incident Identifier is
    an automatically generated unique identifier that will be the same on
    any computer which encounters the problem. (Similar to Full Circle
    Software's TalkBack ID and Bugtoaster's Crash Signature.)
    

License
===============================================================================
    Copyright (c) 2003 Not Another Corporation Incorporated
                       www.notanothercorporation.com

    GNU LGPL - See individual files for details


Installation
===============================================================================
    
    For site-wide availability:
      python setup.py install
    
    For availability to one Python script:
      Copy the 'mongoose' directory (containing the '__init__.py' file) to
      the same directory as your script (or some other directory on its
      path.)
        

Homepage
===============================================================================
    http://www.notanothercorporation.com/source/mongoose.html


Documentation
===============================================================================
    
        
    Mongoose replaces the default system exception handler with its own
    which calls "reporters" in the event that an exception occurs.
    
    
    Basic usage example
    ~~~~~~~~~~~~~~~~~~~
    
      import mongoose
    
      mongoose.start()
      mongoose.registerReporter(FileLogReporter('mongoose.log'))
      mongoose.setSessionInfo('app_version', '1.0')
      # < ... your code here ... >
      mongoose.stop()
    
    Where 'FileLogReporter' is a sub-class of 'mongoose.Reporter'.
    
    The 'mongoose.start()' can also go after
    'mongoose.registerReporter()' but exceptions from the reporter
    registration won't be caught.
    
    
    Sample reporter output
    ~~~~~~~~~~~~~~~~~~~~~~
    
    To see the results of all the sample reporters on your own system type:
    
    python mongoose/reporters.py [<smtp mail server> <to address>]
    
    
    ConsoleReporter
    ---------------
    This program has encountered a problem that means it can not continue.
    
    Please contact your technical support provider, system
    administrator or the vendor of this software and ask them for
    assistance.
    
    Mongoose Incident Identifier: 89662
    
    
    FileLogReporter (Short format - see file 'temp.log')
    ---------------
    Mon Mar  3 15:50:23 2003	89662	exceptions.Exception	Dummy Exception
    
    
    FileLogReporter (Long format - see file 'ltemp.log')
    ---------------
    ------------------------------------------------------------------------
    Mon Mar  3 15:50:23 2003	89662	exceptions.Exception	Dummy Exception
    
    Traceback (most recent call last):
      File "mongoose/reporters.py", line 491, in ?
        raise Exception("Dummy Exception")
    Exception: Dummy Exception
    
    info one: Stuff
    info two: A value
    ------------------------------------------------------------------------
    
    EmailReporter
    ---------------
    From: mongoose@example.com
    To: developer@example.com
    Subject: Mongoose Incident Report
    X-Mongoose-Id: 89662
    Date: Mon,  3 Mar 2003 15:50:23 -0800 (PST)
    
    (This is an optional message prologue.)
    ------------------------------------------------------------------------
    Mon Mar  3 15:50:23 2003	89662	exceptions.Exception	Dummy Exception
    
    Traceback (most recent call last):
      File "mongoose/reporters.py", line 491, in ?
        raise Exception("Dummy Exception")
    Exception: Dummy Exception
    
    info one: Stuff
    info two: A value
    ------------------------------------------------------------------------
    
    
    About "Mongoose Incident Identifiers(TM)"
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    A "Mongoose Incident Identifier" (MII) provides developers a
    convenient way to track the same exceptional incident (i.e. "bug") on
    multiple computers. A Mongoose Incident Identifier is an automatically
    generated unique identifier that will be the same on any computer
    which encounters the problem.  (Similar to Full Circle Software's
    TalkBack ID and Bugtoaster's Crash Signature.)
    
    The following is an example MII:
    
    89662
    
    Exciting, huh? 
    
    Why is a Mongoose Incident Identifier good for users?
    -----------------------------------------------------
    
    Error messages and tracebacks resulting from uncaught exceptions
    normally generate too much information to be conveniently conveyed to
    support personnel over the phone, or search for on a software vendor's
    web site support database.
    
    A MII allows the user to have one small, easy to remember piece of
    information to identify their problem. They can then search the
    vendor's support database or talk to support personnel.
    
    
    Why is a Mongoose Incident Identifier good for support staff?
    -------------------------------------------------------------
    
    Because the MII for any particular incident is the same no matter what
    computer the software is installed on, a MII can help support staff
    more quickly ascertain whether the current bug has been seen before,
    and find out if there are known solutions or work-arounds for it.
    
    When an MII is reported by users for the first time there is no
    information known about it. Once the MII's corresponding traceback 
    (file or email) log is retrieved, developers can begin investigating a
    solution or work around, and keep support staff informed with a
    progress report linked by the MII. This means when another user
    reports the same MII support staff can quickly let them know the
    current status of the solution.
    
    
    Why is a Mongoose Incident Identifier good for developers?
    ----------------------------------------------------------
    
    A MII has two main benefits for developers:
    
    * Helping to determine which bugs should be a priority by noting the
      relative frequency of each MII.
    
    * Providing a convenient method of conveying information from the user
      to the developer about particular bugs. Once a bug has an MII
      associated with it the developer can also link the logged traceback
      (including custom session information) and other information to it.
    
    
    How is a Mongoose Incident Identifier generated?
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    This is the implementation specific, technical bit, you don't need to
    know this to use MIIs, and you shouldn't rely on the exact method of
    generating MIIs in the current implementation either.
    
    At present a MII is generated by extracting function names from
    the traceback of the uncaught exception and concatenating them into a
    string, getting a hash for that string and then using the value of
    the hash modulo 10000.
    
    This method has some pros and cons:
    
    Pros:
    
     +  The MII for an incident is constant between different versions of
        the software if the error should (heaven forbid) not be fixed in a
        newer version. If a source file is edited, insertion or deletion of
        lines doesn't affect the MII generated.
    
     +  The MII is a small value, easy to remember or record.
    
    Cons:
    
     +  The MII may *not* actually be unique (1). The finest granularity a
        MII can refer to is the function level. This means that if the last
        function in a particular function call path can generate two
        uncaught exceptions they will both have the same MII. The actual
        line number of the exception in the logged traceback will highlight
        this.
    
     +  The MII may *not* actually be unique (2). There is a chance that the
        same MII may refer to two different incidents by virtue of the fact
        that the hash for a particular sequence of function paths could be
        the same, or the fact that there are only 100,000 possible MII due
        to our use of modulo. But as this is an edge case (same hash for
        different sequence of function calls or modulo 100,000 clashing) of
        an edge case (uncaught exception) I don't think it's a big issue.
    
    
    It is possible for an MII to have an extended form but this is not
    currently implemented. An MII in extended form looks like:
    
    501-89662-72
    
    where the first number is the software release version, the second
    number the simple MII and the last number the line number (possibly
    modulo 100) of the file where the exception occurred. This form
    reduces the likelihood of a MII clash caused by two different
    exceptions in one function. If there is sufficient demand for this form
    it may be added.
    
    
    More documentation
    ~~~~~~~~~~~~~~~~~~
    
    Mongoose source code uses Epydoc <http://epydoc.sourceforge.net/>
    compatible docstrings, feel free to read them. These will be
    particularly useful if you want to develop your own reporter. (e.g. to
    page some hapless SysAdmin; record a MII & log to a web site; send a
    message to a remote system monitor, etc...)
    
    
    Other Limitations
    ~~~~~~~~~~~~~~~~~
    
    We're not gonna catch a segfault, okay? (This belongs in the realm of
    a non-Python specific Open Source implementation of this
    functionality.)
    
    
    Utility modules
    ~~~~~~~~~~~~~~~
    
    'runall.py' - Executes all the unit tests found in the 'test'
    directory. Can be used to do this in your packages too.
    
    'test/extunit.py' - A special type of unit test class that allows us to 
    unit test functionality that would otherwise disrupt or be disrupted by 
    the standard Python 'unittest' framework. This is how we unit test our 
    replacement system exception handler (otherwise the unit test framework 
    would catch all the uncaught exceptions). This can be used in your own 
    test suites also, it's internally documented, but the documentation 
    probably needs elaboration.
    
        


Revision History
===============================================================================
    0.1 - initial

    