This client library reports exceptions to Squash, the Squarish exception reporting and management system.
Comprehensive documentation is written in ReST-formatted comments
throughout the source. To view this documentation as an HTML site, run sphinx
with (cd doc; make html). If sphinx is not installed, run pip install sphinx.
The starting HTML file is at doc/_build/html/index.html.
For an overview of the various components of Squash, see the website documentation at https://github.com/SquareSquash/web.
This library is compatible with projects written using Python 2.7 and above,
and Python 3.2 and above. It may also be compatible with Python 2.6 and Python 3.1, if
the argparse module is installed.
This library was created for use with Python 2.7. Patches to improve compatibility with python 2.6 or python 3+ are welcome.
Requires argparse on certain older Python versions; see Compatibility above.
Unpack the source distribution, then run python setup.py install to
install squash_python into your site-packages folder. Consider using
virtualenv beforehand to install it into a site-packages folder
specific to your project instead of the system-wide folder
Add the following code somewhere in your application that gets invoked on
startup, such as your app's main function::
import squash_python
client = squash_python.get_client()
client.APIKey = "YOUR_API_KEY"
client.environment = "production"
client.host = "https://your.squash.host"
client.revision = "GIT_REVISION_OF_RELEASED_PRODUCT"
client.reportErrors()
client.hook()
.. tip: Use git rev-parse to translate a commit-ish (such as a branch or tag name)
into a commit ID for the revision field.
The reportErrors method loads any errors recorded from previous crashes and
transmits them to Squash. Errors are only removed from this queue when Squash
successfully receives them. Exceptions are transmitted to Squash using
JSON-over-HTTPS. A default API endpoint is pre-configured. (see notifyPath
below)
the hook method uses sys.excepthook to add the uncaught-exception handler
that allows Squash to record new crashes.
A third method recordException can be used to report non-fatal exceptions
caught by your application. Its arguments are the same as those provided by sys.exc_info
and accepted by sys.excepthook. Typical usage::
client.recordException(*sys.exc_info())
The squash_python module logs information about successes and failures
to the standard logging module. Failures are logged to WARN, successes
are logged to INFO, and plenty of other stuff is logged to DEBUG.
To quickly enable this module and see its output, use the following code::
import logging
logging.basicConfig(level=logging.DEBUG)
You can configure the client using the attributes of the
singleton instance returned by squash_python.get_client().
The following attributes are available:
host:
Required. The host on which Squash is running. e.g. "https://squash.example.com:3000"
APIKey:
Required. The API key of the project that exceptions will be associated with.
This configuration option is required. The value can be found by going to the
project's home page on Squash.
environment:
Required. The environment that exceptions will be associated with.
This should be a string such as "development", "testing", or "production"
revision:
Required. The revision of the Git repository that was compiled to make this
build. This ought to be a commit ID (for git, a SHA-1 hash).
build:
For released apps, the machine-readable build number or build identifer that matches the revision.
version:
For released apps, the human-readable version number.
disabled:
If YES, the Squash client will not report any errors.
notifyPath:
The path to post new exception notifications to. By default it's
set to /api/1.0/notify.
timeout:
The amount of time to wait before giving up on transmitting an
error. By default it's 15 seconds.
ignoredExceptions:
A set of Exception names or Exception subclasses that
will not be reported to Squash.
handledSignals:
A set of signals (represented as a list of integers) that Squash
will trap. By default it's SIGABRT, SIGBUS, SIGFPE, SIGILL, SIGSEGV,
and SIGTRAP. (On win32, SIGBUS and SIGTRAP are not available; see :mod:signal)
filterStrings:
Strings to remove from the exception's message.
These keys might contain sensitive or personal information, for
example. In addition, the location of the user's home folder is
removed and replaced with ~
args:
Dictionary of additional keys and values to add to each reported occurrence.
The squash_python module also installs two command line scripts called squash_release
and squash_tester.
You must use squash_release to notify Squash of a new deployment. Run squash_release to
have it print its usage information.
You can use squash_tester to test your Squash integration, or as a template to integrating
Squash into your own project. The easiest way to use squash_tester is to
run the Squash web server locally on port 3000, and set the environment variable
SQUASH_TESTER_API_KEY to the API key of a project you create in your local web
server. Once that is done, you may run squash_tester to report an uncaught exception, or
run squash_tester -s to report an unhandled signal.
If the server is running elsewhere, you may set the environment variable SQUASH_TESTER_HOST
to the method, host and port of the server (e.g. "https://squash.example.com:3000")