{"_id":"panic","_rev":"6-39d2729aae7cd188c4738d473a672cbf","name":"panic","description":"Postmortem debugging facility","dist-tags":{"latest":"0.2.1"},"versions":{"0.0.1":{"name":"panic","version":"0.0.1","description":"Postmortem debugging facility","author":{"name":"Joyent","url":"joyent.com"},"engines":{"node":"*"},"main":"./lib/panic","repository":{"type":"git","url":"git://github.com/joyent/node-panic.git"},"_npmJsonOpts":{"file":"/Users/dap/.npm/panic/0.0.1/package/package.json","wscript":false,"contributors":false,"serverjs":false},"_id":"panic@0.0.1","dependencies":{},"devDependencies":{},"_engineSupported":true,"_npmVersion":"1.0.18","_nodeVersion":"v0.4.9","_defaultsLoaded":true,"dist":{"shasum":"9673181131417f0016a9ac7893d1deb803e15d4b","tarball":"https://registry.npmjs.org/panic/-/panic-0.0.1.tgz","integrity":"sha512-hk/zLiuBsMo4VwFSvc5D1nE5sf6g7gYW8F2sj0hzprF4Jaj10NVq2jwvHXBvQHiAnulOmeKBb93x/Z97uO46ow==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDm0UnoV4U7mJpJ5XJXltq0KnpPi5/A0varQVnReqfyuwIhAIlDPDm0BFZAAbEJMn3FvAS3kpfjt36BgB8VuudzJhkQ"}]},"scripts":{},"maintainers":[{"name":"dap","email":"dap@cs.brown.edu"}]},"0.1.0":{"name":"panic","version":"0.1.0","description":"Postmortem debugging facility","author":{"name":"Joyent","url":"joyent.com"},"engines":{"node":"*"},"main":"./lib/panic","repository":{"type":"git","url":"git://github.com/joyent/node-panic.git"},"_npmJsonOpts":{"file":"/Users/dap/.npm/panic/0.1.0/package/package.json","contributors":false,"serverjs":false,"wscript":false},"_id":"panic@0.1.0","dependencies":{},"devDependencies":{},"_engineSupported":true,"_npmVersion":"1.0.18","_nodeVersion":"v0.4.9","_defaultsLoaded":true,"dist":{"shasum":"34c2397320dfa48954cc98543c8eee50aca60476","tarball":"https://registry.npmjs.org/panic/-/panic-0.1.0.tgz","integrity":"sha512-Q7uCJRntdRTTsUU9bYaUQ4gzPY7TIoZ07wvJvnOZUNUxFEDMvhOjoDU/dyUbqCiyRHRxfnoDXUJ5yD+AukFBcg==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDsWK/CNAhLCUi88FhFKXXFBCBohOo5//zZYo0O1PN46wIgWaciI548IpCO5zvY9eoR2fULWoOhL/hRziO+p4lfV78="}]},"scripts":{},"maintainers":[{"name":"dap","email":"dap@cs.brown.edu"}]},"0.1.1":{"name":"panic","version":"0.1.1","description":"Postmortem debugging facility","author":{"name":"Joyent","url":"joyent.com"},"engines":{"node":"*"},"main":"./lib/panic","repository":{"type":"git","url":"git://github.com/joyent/node-panic.git"},"bin":{"ncore":"cmd/ncore.js"},"_npmJsonOpts":{"file":"/Users/dap/.npm/panic/0.1.1/package/package.json","contributors":false,"wscript":false,"serverjs":false},"_id":"panic@0.1.1","dependencies":{},"devDependencies":{},"_engineSupported":true,"_npmVersion":"1.0.18","_nodeVersion":"v0.4.9","_defaultsLoaded":true,"dist":{"shasum":"a527b044429728aa73b34ceb817e897405dd40d8","tarball":"https://registry.npmjs.org/panic/-/panic-0.1.1.tgz","integrity":"sha512-IP90aZ50bzwIZb3XOnsswzCU34t7gG0/11jFjIj6hlTuUa+qSgFGXdeXGXu/dDX+/Eqbzmm9MZH6mY986MonuA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC8/QdMpJEMuM840ZQm4Cp+WXRVsuFlSC+Omq6EtElTKwIhALpTWTDw3SZl/69GpkKvOdRx6aJi0cNYNcUbLQ+kKRSj"}]},"scripts":{},"maintainers":[{"name":"dap","email":"dap@cs.brown.edu"}]},"0.1.2":{"name":"panic","version":"0.1.2","description":"Postmortem debugging facility","author":{"name":"Joyent","url":"joyent.com"},"engines":{"node":"*"},"main":"./lib/panic","repository":{"type":"git","url":"git://github.com/joyent/node-panic.git"},"bin":{"ncore":"cmd/ncore.js"},"_npmUser":{"name":"dap","email":"dap@cs.brown.edu"},"_id":"panic@0.1.2","dependencies":{},"devDependencies":{},"optionalDependencies":{},"_engineSupported":true,"_npmVersion":"1.1.1","_nodeVersion":"v0.6.10","_defaultsLoaded":true,"dist":{"shasum":"62e8185a86fce9d62f301c50500ceb3648ef5476","tarball":"https://registry.npmjs.org/panic/-/panic-0.1.2.tgz","integrity":"sha512-evEWVB8mZawevRzAzwSZOE6B/510N+v5oYplMpV9ZoQNAJe0zVXrAXvbA8DKdxlV//me/OHHiK70zfpOCIlykw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCICsKfXnxmWZoXAYZl7A15OP/hsZLGscYV71SJ57BHu+JAiEAo74+iDhlNEb3Tnd+VpkM5jzygWysAE29FlM99U/nkYM="}]},"maintainers":[{"name":"dap","email":"dap@cs.brown.edu"}]},"0.2.0":{"name":"panic","version":"0.2.0","description":"Postmortem debugging facility","author":{"name":"Joyent","url":"joyent.com"},"engines":{"node":"*"},"main":"./lib/panic","repository":{"type":"git","url":"git://github.com/joyent/node-panic.git"},"bin":{"ncore":"cmd/ncore.js"},"_npmUser":{"name":"dap","email":"dap@cs.brown.edu"},"_id":"panic@0.2.0","dependencies":{},"devDependencies":{},"_engineSupported":true,"_npmVersion":"1.0.94","_nodeVersion":"v0.4.2","_defaultsLoaded":true,"dist":{"shasum":"45116bf383ca771a445fe64b939a94f8beb3d740","tarball":"https://registry.npmjs.org/panic/-/panic-0.2.0.tgz","integrity":"sha512-jZV+OdwNS2/v+BPxH7A4pR33agqa9uyqsDHTmMI9AnYfq+2ZVA3ze1Wjy0tRY84UhLTNVn9IpWPzp7KClFhuvw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCHBEJv8P5IxMkJpHgxiu6XWFYa2LDuj6UVP0VMVEuK4QIgd4vsGhv8YUm3XAyCkP9K5gsJ4lcLSOTorZ0TXVa6nBw="}]},"maintainers":[{"name":"dap","email":"dap@cs.brown.edu"}]},"0.2.1":{"name":"panic","version":"0.2.1","description":"Postmortem debugging facility","author":{"name":"Joyent","url":"joyent.com"},"engines":{"node":"*"},"main":"./lib/panic","repository":{"type":"git","url":"git://github.com/joyent/node-panic.git"},"bin":{"ncore":"cmd/ncore.js"},"_npmUser":{"name":"dap","email":"dap@cs.brown.edu"},"_id":"panic@0.2.1","dependencies":{},"devDependencies":{},"_engineSupported":true,"_npmVersion":"1.0.94","_nodeVersion":"v0.4.2","_defaultsLoaded":true,"dist":{"shasum":"3709a2fe0c112b3763a5b277cf334d7d6737f63d","tarball":"https://registry.npmjs.org/panic/-/panic-0.2.1.tgz","integrity":"sha512-aMYwbzaEXmotLMxZwjOW/ueBTO70DwKqqMFz+7JRPIjKlSzIexolSBZHLfZ1U4E6h4ZwzxeGJ0Go4G/qeR5AMA==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQD9tIqm4Qeb5XvAtht/IMjmbaGemCMReDgBq+D5p5gUOgIgZjtweQp838QN1ou4jwAH6QF4ovxXYvIytJqyUcG0kr4="}]},"maintainers":[{"name":"dap","email":"dap@cs.brown.edu"}]}},"maintainers":[{"name":"dap","email":"dap@cs.brown.edu"}],"time":{"modified":"2022-06-23T08:56:36.009Z","created":"2011-09-13T17:42:15.232Z","0.0.1":"2011-09-13T17:42:15.715Z","0.1.0":"2011-09-13T18:38:51.853Z","0.1.1":"2011-09-13T19:42:16.507Z","0.1.2":"2012-03-08T01:00:43.622Z","0.2.0":"2012-04-25T23:07:06.556Z","0.2.1":"2012-04-25T23:12:33.289Z"},"author":{"name":"Joyent","url":"joyent.com"},"repository":{"type":"git","url":"git://github.com/joyent/node-panic.git"},"readme":"```\n________                    __    __________               .__        \n\\______ \\   ____   ____ | _/  |_  \\______   \\_____    ____ |__| ____  \n |    |  \\ /  _ \\ /    \\  \\   __\\  |     ___/\\__  \\  /    \\|  |/ ___\\ \n |    `   (  <_> )   |  \\  |  |    |    |     / __ \\|   |  \\  \\  \\___ \n/_______  /\\____/|___|  /  |__|    |____|    (____  /___|  /__|\\___  >\n        \\/            \\/                          \\/     \\/        \\/ \n```\n\nnode-panic\n===============\n\nThis module provides a primitive postmortem debugging facility for Node.js.\nPostmortem debugging is critical for root-causing issues that occur in\nproduction from the artifacts of a single failure.  Without such a facility,\ntracking down problems in production becomes a tedious process of adding\nlogging, trying to reproduce the problem, and repeating until enough information\nis gathered to root-cause the issue.  For reproducible problems, this process is\nmerely painful for developers, administrators, and customers alike.  For\nunreproducible problems, this is untenable.\n\nThe basic idea of this implementation is to maintain a global object that\nreferences all of the internal state we would want for postmortem debugging.\nThen when our application crashes, we dump this state to a file, and then exit.\n\n\nThe basics\n----------\n\nThere are only a few functions you need to know about.  The first time this\nmodule is loaded, it creates a global object called `panicDbg` to manage program\ndebug state.\n\n* `panicDbg.set(key, value)`: registers the object `value` to be dumped under\n  the key `key` when the program panics.  This function replaces the value from\n  any previous call with the same key.\n* `panicDbg.add(keybase, value)`: like panicDbg.set, but generates a unique key\n  based on `keybase`.\n* `mod_panic.panic(msg, err)`: dumps the given error message an optional\n  exception as well as all registered debug state to a file called\n  \"ncore.<pid>\" and then exits the program.\n* `mod_panic.enablePanicOnCrash()`: sets up the program to automatically invoke\n  `mod_panic.panic` when an uncaught exception bubbles to the event loop\n\nWhen the program panics (crashes), it saves all debug state to a file called\n\"ncore.<pid>\".  This file is pure JSON and is best read using the \"json\" tool at:\n\n    https://github.com/trentm/json\n\nIn the example above, the program first invokes `enablePanicOnCrash` to set up\nautomatic panicking when the program crashes.  As each function is invoked, it\nadds its argument to the global debug state.  After the program crashes, you\ncan see the saved state as \"func1.arg\" and \"func2.arg\" in the dump.\n\n\nExample\n--------\n\nFirst, a simple program:\n\n    $ cat examples/example-auto.js \n    /*\n     * example-auto.js: simple example of automatically panicking on crash\n     */\n    \n    var mod_panic = require('panic');\n    \n    function func1(arg1)\n    {\n    \t/* include func1 arg in debug state */\n    \tpanicDbg.set('func1.arg', arg1);\n    \tfunc2(arg1 + 10);\n    }\n    \n    function func2(arg2)\n    {\n    \t/* include func2 arg in debug state */\n    \tpanicDbg.set('func2.arg', arg2);\n    \t/* crash */\n    \t(undefined).nonexistentMethod();\n    }\n    \n    /*\n     * Trigger a panic on crash.\n     */\n    mod_panic.enablePanicOnCrash();\n    \n    /*\n     * The following line of code will cause this Node program to exit after dumping\n     * debug state to ncore.<pid> (including func1's and func2's arguments).\n     */\n    func1(10);\n    console.error('cannot get here');\n\n\nRun the program:\n\n    $ node examples/example-auto.js \n    [2011-09-12 22:37:36.410 UTC] CRIT   PANIC: panic due to uncaught exception: EXCEPTION: TypeError: TypeError: Cannot call method 'nonexistentMethod' of undefined\n        at func2 (/home/dap/node-postmortem/examples/example-auto.js:19:14)\n        at func1 (/home/dap/node-postmortem/examples/example-auto.js:11:2)\n        at Object.<anonymous> (/home/dap/node-postmortem/examples/example-auto.js:31:1)\n        at Module._compile (module.js:402:26)\n        at Object..js (module.js:408:10)\n        at Module.load (module.js:334:31)\n        at Function._load (module.js:293:12)\n        at Array.<anonymous> (module.js:421:10)\n        at EventEmitter._tickCallback (node.js:126:26)\n    [2011-09-12 22:37:36.411 UTC] CRIT   writing core dump to /home/dap/node-postmortem/ncore.22984\n    [2011-09-12 22:37:36.413 UTC] CRIT   finished writing core dump\n\n\nView the \"core dump\":\n\n    $ json < /home/dap/node-postmortem/ncore.22984\n    {\n      \"dbg.format-version\": \"0.1\",\n      \"init.process.argv\": [\n        \"node\",\n        \"/home/dap/node-panic/examples/example-auto.js\"\n      ],\n      \"init.process.pid\": 22984,\n      \"init.process.cwd\": \"/home/dap/node-panic\",\n      \"init.process.env\": {\n        \"HOST\": \"devel\",\n        \"TERM\": \"xterm-color\",\n        \"SHELL\": \"/bin/bash\",\n        \"USER\": \"dap\",\n        \"PWD\": \"/home/dap/node-panic\",\n        \"MACHINE_THAT_GOES_PING\": \"1\",\n        \"SHLVL\": \"1\",\n        \"HOME\": \"/home/dap\",\n        \"_\": \"/usr/bin/node\"\n      },\n      \"init.process.version\": \"v0.4.9\",\n      \"init.process.platform\": \"sunos\",\n      \"init.time\": \"2011-09-12T22:37:36.408Z\",\n      \"init.time-ms\": 1315867056408,\n      \"func1.arg\": 10,\n      \"func2.arg\": 20,\n      \"panic.error\": \"EXCEPTION: TypeError: TypeError: Cannot call method 'nonexistentMethod' of undefined\\n    at func2 (/home/dap/node-postmortem/examples/example-auto.js:19:14)\\n    at func1 (/home/dap/node-postmortem/examples/example-auto.js:11:2)\\n    at Object.<anonymous> (/home/dap/node-postmortem/examples/example-auto.js:31:1)\\n    at Module._compile (module.js:402:26)\\n    at Object..js (module.js:408:10)\\n    at Module.load (module.js:334:31)\\n    at Function._load (module.js:293:12)\\n    at Array.<anonymous> (module.js:421:10)\\n    at EventEmitter._tickCallback (node.js:126:26)\",\n      \"panic.time\": \"2011-09-12T22:37:36.408Z\",\n      \"panic.time-ms\": 1315867056408,\n      \"panic.memusage\": {\n        \"rss\": 13000704,\n        \"vsize\": 73252864,\n        \"heapTotal\": 3196160,\n        \"heapUsed\": 1926592\n      }\n    }\n\n\nWhat's in the dump\n------------------\n\nThe dump itself is just a JSON object.  This module automatically fills in the following keys:\n\n* dbg.format-version: file format version\n* init.process.argv: value of process.argv (process arguments)\n* init.process.pid: value of process.pid (process identifier)\n* init.process.cwd: value of process.cwd (process working directory)\n* init.process.env: value of process.env (process environment)\n* init.process.version: value of process.version (Node.js version)\n* init.process.platform: value of process.platform (operating system)\n* init.time: time at which node-panic was loaded\n* init.time-ms: time in milliseconds at which node-panic was loaded\n* panic.error: string description of the actual error that caused the panic (includes stack trace)\n* panic.time: time at which the panic occurred\n* panic.time: time in milliseconds at which the panic occurred\n* panic.memusage: memory used when the panic occurred\n\n*plus* any information added with `panicDbg.set` or `panicDbg.add`.\n\n\nGenerating dumps from outside the program\n-----------------------------------------\n\nnode-panic includes a tool called \"ncore\" for causing a node program that's\nalready loaded node-panic to dump core on demand *without* any other cooperation\nfrom the program itself.  That is, even if the program is stuck inside an\ninfinite loop, \"ncore\" can interrupt it to take a core dump.\n\nCaveat: this tool can be very dangerous!  Since it uses SIGUSR1, invoking it on\nnon-node processes can result in all kinds of failure.  (On Illumos systems,\n\"ncore\" will automatically detect this case and bail out.)  Additionally, if\nanother program on the same system is using the node debugger, ncore will fail.\n\"ncore\" tries to avoid hijacking another debugger session, but this check is\ninherently racy.  Because of these risks, this tool should be viewed as a last\nresort, but it can be extremely valuable when needed.\n\nLet's take a look at how it works:\n\n    $ cat examples/example-loop.js \n    /*\n     * example-loop.js: example of using \"ncore\" tool to generate a node core\n     */\n    \n    var mod_panic = require('panic');\n    \n    function func()\n    {\n    \tfor (var ii = 0; ; ii++)\n    \t\tpanicDbg.set('func-iter', ii);\n    }\n    \n    console.log('starting infinite loop; use \"ncore\" tool to generate core');\n    func();\n\nNow run the program:\n\n    $ node examples/example-loop.js\n    starting infinite loop; use \"ncore\" tool to generate core\n\nIn another shell, run \"ncore\" on the given program:\n\n    $ ncore 1369\n    attempting to attach to process 1369 ... . ok.\n\nAnd back in the first shell we see:\n\n    Hit SIGUSR1 - starting debugger agent.\n    debugger listening on port 5858[2011-09-13 19:20:38.265 UTC] CRIT   PANIC:\n    explicit panic: EXCEPTION: Error: Error: core dump initiated at user request\n        at caPanic (/Users/dap/work/node-panic/lib/panic.js:55:9)\n        at eval at func (/Users/dap/work/node-panic/examples/example-loop.js:9:23)\n        at ExecutionState.evaluateGlobal (native)\n        at DebugCommandProcessor.evaluateRequest_ (native)\n        at DebugCommandProcessor.processDebugJSONRequest (native)\n        at DebugCommandProcessor.processDebugRequest (native)\n        at func (/Users/dap/work/node-panic/examples/example-loop.js:9:23)\n        at Object.<anonymous>\n    (/Users/dap/work/node-panic/examples/example-loop.js:14:1)\n        at Module._compile (module.js:402:26)\n        at Object..js (module.js:408:10)\n    [2011-09-13 19:20:38.265 UTC] CRIT   writing core dump to\n    /Users/dap/work/node-panic/ncore.1369\n    [2011-09-13 19:20:38.294 UTC] CRIT   finished writing core dump\n\nAnd we now have a core dump from the process somewhere in the middle of the\nloop:\n\n    $ json < ncore.1369 \n    {\n      \"dbg.format-version\": \"0.1\",\n      \"init.process.argv\": [\n        \"node\",\n        \"/Users/dap/work/node-panic/examples/example-loop.js\"\n      ],\n      \"init.process.pid\": 1369,\n      \"init.process.cwd\": \"/Users/dap/work/node-panic\",\n      ...\n      \"func-iter\": 604762552,\n      \"panic.error\": \"EXCEPTION: Error: Error: core dump initiated at user request\\n\n    at caPanic (/Users/dap/work/node-panic/lib/panic.js:55:9)\\n    at eval at func\n    (/Users/dap/work/node-panic/examples/example-loop.js:9:23)\\n    at\n    ExecutionState.evaluateGlobal (native)\\n    at\n    DebugCommandProcessor.evaluateRequest_ (native)\\n    at\n    DebugCommandProcessor.processDebugJSONRequest (native)\\n    at\n    DebugCommandProcessor.processDebugRequest (native)\\n    at func\n    (/Users/dap/work/node-panic/examples/example-loop.js:9:23)\\n    at\n    Object.<anonymous> (/Users/dap/work/node-panic/examples/example-loop.js:14:1)\\n\n    at Module._compile (module.js:402:26)\\n    at Object..js (module.js:408:10)\",\n    }\n\n\nNotes\n-----\n\nThis facility was initially developed for Joyent's Cloud Analytics service.\nFor more information on Cloud Analytics, see http://dtrace.org/blogs/dap/files/2011/07/ca-oscon-data.pdf\n\nPull requests accepted, but code must pass style and lint checks using:\n\n* style: https://github.com/davepacheco/jsstyle\n* lint: https://github.com/davepacheco/javascriptlint\n\nThis facility has been tested on MacOSX and Illumos with Node.js v0.4.  It has\nfew dependencies on either the underlying platform or the Node version and so\nshould work on other platforms.\n","readmeFilename":"","users":{"honzajde":true}}