From 295eb1c457d2f693595cce2d205f1e61660f08a5 Mon Sep 17 00:00:00 2001 From: Josh Gavant Date: Mon, 18 Apr 2016 09:49:34 -0700 Subject: [PATCH] Initial READMEs for domains. --- README.md | 20 ++++++++++++-------- debugging/README.md | 29 +++++++++++++++++++++++++++++ heap-memory/README.md | 10 ++++++++++ profiling/README.md | 26 ++++++++++++++++++++++++++ tracing/README.md | 6 +++++- tracing/os-tracing/README.md | 16 ++++++++++------ 6 files changed, 92 insertions(+), 15 deletions(-) create mode 100644 debugging/README.md create mode 100644 heap-memory/README.md create mode 100644 profiling/README.md diff --git a/README.md b/README.md index 57aa4be..cd6e911 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,24 @@ # Diagnostics Working Group The goal of this WG is to ensure Node provides a set of comprehensive, documented, extensible diagnostic protocols, formats, and APIs to enable tool vendors to provide reliable diagnostic tools for Node. -To facilitate this, work is divided into several domains: -- Tracing and Logging -- Profiling -- Heap and Memory Analysis -- Step Debugging -- Protocol and API +Work is divided into several domains: +- [Tracing](./tracing) +- [Profiling](./profiling) +- [Heap and Memory Analysis](./heap-memory) +- [Step Debugging](./debugging) Background, reference documentation, samples, and discussion for each domain is contained within its folder. -# Logistics +Work needed includes: +- Collect, understand, and document existing diagnostic capabilities and entry-points throughout Node, V8, and other components. +- Collect and document projects and products providing diagnostics for Node with brief description of their technical architecture and sponsoring organizations. +- Identify opportunities and gaps, then propose and implement solutions. + +### Logistics - Monthly Meetings - Biannual F2F -# Members +### Members * @bnoordhuis * @sam-github * @othiym23 diff --git a/debugging/README.md b/debugging/README.md new file mode 100644 index 0000000..727dc3b --- /dev/null +++ b/debugging/README.md @@ -0,0 +1,29 @@ +## Debugging API +- [Chrome Debugging Protocol](https://chromedevtools.github.io/debugger-protocol-viewer/) +- [V8 Debugging Protocol](https://github.com/v8/v8/wiki/Debugging-Protocol) + +Node currently relies on V8's internal Debug API and associated commands and events. The Debug API is published at [v8/include/v8-debug.h](https://github.com/v8/v8/blob/master/include/v8-debug.h), and the message protocol is documented in prose in [the V8 wiki](https://github.com/v8/v8/wiki/Debugging-Protocol) and in code in [v8/src/debug/debug.js#L2341-2372](https://github.com/v8/v8/blob/master/src/debug/debug.js#L2341-L2372). + +Node also provides an agent [node/src/debug-agent.h](https://github.com/blob/master/src/debug-agent.h) which relays requests, responses, and events through a TCP socket, and a command-line debugger [node/lib/_debugger.js](https://github.com/blob/master/lib/_debugger.js). + +The Chrome/V8 team has deprecated the internal V8 API and command set and proposed replacing it with a subset of the Chrome Debugging Protocol (CrDP), see https://github.com/nodejs/node/issues/2546. CrDP is documented at [https://chromedevtools.github.io/debugger-protocol-viewer/]() and the backing GitHub repo. + +The [cyrus-and/chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface) library provides a JS proxy for CrDP. + +## Step Debugging Tools +Name | Sponsor +-----|-------- +[node-inspector][] | StrongLoop +[JetBrains WebStorm][] | JetBrains +[Visual Studio Code][] | Microsoft +[Node CLI Debugger][] | Node Foundation +[Chrome DevTools][] | Google +[Theseus][] | Adobe Research + +[node-inspector]: https://github.com/node-inspector/node-inspector +[JetBrains WebStorm]: https://www.jetbrains.com/help/webstorm/2016.1/running-and-debugging-node-js.html +[Visual Studio Code]: https://github.com/Microsoft/vscode +[Node CLI Debugger]: https://nodejs.org/api/debugger.html +[Chrome DevTools]: https://github.com/ChromeDevTools/devtools-frontend +[Theseus]: https://github.com/adobe-research/theseus + diff --git a/heap-memory/README.md b/heap-memory/README.md new file mode 100644 index 0000000..14f7a93 --- /dev/null +++ b/heap-memory/README.md @@ -0,0 +1,10 @@ +## Heap and Memory Analysis +The [nodejs/post-mortem](https://github.com/nodejs/post-mortem) WG is responsible for this domain. + +### Heap Analysis +- [mdb_v8](https://github.com/joyent/mdb_v8) +- [node-heapdump](https://github.com/bnoordhuis/node-heapdump) +- [llnode](https://github.com/indutny/llnode) +- [IBM IDDE](https://www.ibm.com/developerworks/java/jdk/tools/idde/) +- [Snapshot Utils](https://github.com/bmeck/snapshot-utils) + diff --git a/profiling/README.md b/profiling/README.md new file mode 100644 index 0000000..7c299ef --- /dev/null +++ b/profiling/README.md @@ -0,0 +1,26 @@ +## Profiling for Node +- CPU Profiling + - V8 CPU Profiler: [v8/include/v8-profiler.h](https://github.com/v8/blob/master/include/v8-profiler.h) + - Accessible globally through `--prof` runtime flag, basic processing and display through `--prof-processor` runtime flag + - Intel vTune profiler. Accessible through `--enable-vtune-profiling` compile-time flag. + +- Heap Profiling + - V8 Heap Profiler: [v8/include/v8-profiler.h](https://github.com/v8/blob/master/include/v8-profiler.h) + - Also accessible through built-in 'v8' module. + +Name | Sponsor +-----|-------- +[v8-profiler][] | StrongLoop +[Chrome DevTools][] | Google + +[v8-profiler]: https://github.com/node-inspector/v8-profiler +[Chrome DevTools]: https://github.com/ChromeDevTools/devtools-frontend + +### Stack Analysis +- [0x](https://github.com/davidmarkclements/0x) +- [StackVis](https://github.com/joyent/node-stackvis) + +## Docs +[guides/simple-profiling](https://nodejs.org/en/docs/guides/simple-profiling/) +[paulirish/automated-chrome-profiling](https://github.com/paulirish/automated-chrome-profiling) + diff --git a/tracing/README.md b/tracing/README.md index 858db3a..2d8ae54 100644 --- a/tracing/README.md +++ b/tracing/README.md @@ -1,5 +1,9 @@ -## Tracing and Logging +## Tracing - [AsyncWrap](./AsyncWrap/README.md) - Most native objects are represented indirectly by the [AsyncWrap class](https://github.com/nodejs/node/blob/master/src/async-wrap.h), so hooks have been added to that class to trace lifecycle (init/destroy) and callback activity (pre/post) related to these objects. + - [OS Tracing](./os-tracing/README.md) - LTTng (Linux), DTrace (Linux, OSX), ETW (Windows) + - [VM Tracing](./vm-tracing/README.md) - Tracing native to JS VMs, such as V8's TRACE_EVENT. +- [Domains and Zones][] - + diff --git a/tracing/os-tracing/README.md b/tracing/os-tracing/README.md index 46f361d..45d4f44 100644 --- a/tracing/os-tracing/README.md +++ b/tracing/os-tracing/README.md @@ -1,20 +1,24 @@ ## OS Tracing * [DTrace](http://dtrace.org/) - Available on IllumOS, Solaris, Mac, Linux - + Available on IllumOS, Solaris, Mac The [DTrace blog](http://dtrace.org/blogs/blog/category/node-js/) has some articles on using DTrace with Node.js * [LTTng](http://lttng.org/) - Linux only. - + Linux only. Some info on using LTTng with Node.js are available in the presentations [Tracing Node on Linux with LTTNG](http://nearform.github.io/tracing-node-lttng-nodejsdublin/) * [ETW](https://msdn.microsoft.com/en-us/library/windows/desktop/aa363668.aspx) - Windows only. - + Windows only. Some information was provided by Bill Ticehurst (@billti) in [issue #10](https://github.com/nodejs/tracing-wg/issues/10#issuecomment-137145822) about how he integrated ETW into Node.js for Windows +* [Perf](https://perf.wiki.kernel.org/) + Linux only. + Can be enabled with `--perf_basic_prof` v8 run-time flag. + +* [SystemTap](https://sourceware.org/systemtap/) + Linux only. +