a cross-language standard (with conversion code) for representing exceptions
Python JavaScript
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
javascript
python
.gitignore
LICENSE-MIT-OSI.txt
README.markdown
package.json

README.markdown

Intro

Common Exception is a cross-language standard for representing an exception as a JSON object.

All fields are optional, and setting a field to null is considered equivalent to omitting it.

{
    "exception": {
        "at": 1292528916674, // ms since 1970
        "name": "...",
        "message": "...",
        "stack": [
            {// most recent stack frame first
                "file_name": "",
                "file_path": "...",
                "file_url": "...",
                "file_sha1": "",        // hex
                "line_number": 100,     // 1-based
                "column_number": 23,    // 1-based
                "byte_offset_start": ,  // num bytes before relevant part
                "byte_offset": ,        // in [byte_offset_start, byte_offset_end]
                "byte_offset_end": ,    // byte_offset_start + len(relevant part)
                "scope_name": "",
                "line": "...line 100...",
                "lines_before": [..., "...98...", "...99..."],
                "lines_after": ["...101...", ...],
                "locals": {
                    // Values intended to be human-readable, not machine-readable
                    // Represent values as strings however you see fit, e.g.
                    "i": "1729",
                    "s": "'long unicode string gets trunca'...",
                    "s": "b'long byte string gets trunca'...",
                    "x": "<__main__.Foo instance at 0x10057e128>",
                    "y": "[1, {2: \"foo\"}]"
                }
            }
        ]
    },
    "environment": {
        "execUrl": // e.g. the page on which client-side JS is being run
        "execAgent": browser user agent, "Python v2.6.1", "NodeJS v0.3.1", ...
        "execPath": 
        "args": sys.argv
        "cwd": "..."
        "pid": 
        "gid": 
        "uid": 
        "env": {
            "PATH": "...",
        }
    },
    "request": {
        "url": "/foo?x=1&y=2",
        "method": "GET", "POST", ...
        "headers": {
            "...": "...",
        }
    },
    "ms_to_create": 5,   // how long it took to create this exception (in the thread where it occurred)
    "build": "..."       // the identifier of the build that was running
    // (e.g. to let your exception-server find source file_sha1 for (build, path/url))
}

This lets you write an exception server, like

or a JavaScript widget, like

  • exception-server's ExceptionWidget

and focus on making it awesome, rather than on writing a batallion of parsers.

Conversion

Python

import common_exception
...
ce = common_exception.fromExceptionText(text)
...
except Exception:
    ce = common_exception.fromCurrentException()
...
ce = common_exception.fromCurrentException(djangoRequest=request, build=BUILD_TOKEN)

JavaScript (NodeJS)

npm install common-exception
var common_exception = require('common_exception');
...
catch(e) {
    var ce = common_exception.fromNodeException(e[, {"request":request}]);
    common_exception.addFileHashes(ce, function(){...});
...
var ce = common_exception.fromBrowserException(e[, {"request":request}]);
// request used for environment.{execAgent,execUrl}

JavaScript (Browser)

// Include browser-ce.min.js (678 bytes) in your code's wrapper function.
// It's of the form "var common_exception_fromException=..."
// so "common_exception_fromException" should minify easily
// e.g. with Closure Compiler's simple mode
// But if you're a JS size fanatic <high five!> you might want to just JSON
// the brower's exception and let your exception server convert it to CE
...
catch(e) {
    var ce = common_exception_fromException(e);
Chrome Safari Firefox IE Opera
name yes yes yes ? ?
message yes yes yes ? ?
# frames all one all ? ?
file_url yes yes yes ? ?
line_number yes yes yes ? ?
column_number yes via offset no ? ?

Efficient encodings

Protobuf

TODO common_exception.proto

Thrift

TODO common_exception.thrift