Skip to content
This repository was archived by the owner on Oct 15, 2020. It is now read-only.

Prefer let and const #476

Merged
kfarnung merged 3 commits into from
Feb 27, 2018
Merged

Prefer let and const #476

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5edf74d
lib: update TTD to use `let` and `const`
kfarnung Feb 23, 2018
2fb4e28
chakrashim: switch `var` to `let` and `const`
kfarnung Feb 23, 2018
2552d1c
doc: fix Markdown linter failures
kfarnung Feb 26, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
# Node.js on ChakraCore

This project enables Node.js to optionally use the [ChakraCore](https://github.com/Microsoft/ChakraCore)
JavaScript engine. This project is still **work in progress** and not an officially
supported Node.js branch. For more context into this project, please refer to the
This project enables Node.js to optionally use the
[ChakraCore](https://github.com/Microsoft/ChakraCore) JavaScript engine. This
project is still **work in progress** and not an officially supported Node.js
branch. For more context into this project, please refer to the
[original PR](https://github.com/nodejs/node/pull/4765).

### How it works
Expand All @@ -19,18 +20,20 @@ to work.

### Time Travel Debugging
Time-Travel debugging is an exciting new addition to Node.js debugging, first
introduced in Node-ChakraCore, and now supported by [VSCode](https://github.com/microsoft/vscode/).
We are developing in the open and want to share our progress to get feedback,
bug reports, functionality requests, and pull-requests from the community.
introduced in Node-ChakraCore, and now supported by
[VSCode](https://github.com/microsoft/vscode/). We are developing in the open
and want to share our progress to get feedback, bug reports, functionality
requests, and pull-requests from the community.

Check out this [Time-Travel Debugging](TTD-README.md)
page to learn how to get started with TTD on Node-ChakraCore with VSCode.

### Node.js API (NAPI)
Node-ChakraCore is an active participant in the [ABI-Stable-Node](https://github.com/nodejs/abi-stable-node)
project also called NAPI. The goal of this project is to ease the lives of native
add-ons developers, by providing a stable Node API which also guarantees stable
ABI across disparate Node versions. This allows native modules to just work across
Node-ChakraCore is an active participant in the
[ABI-Stable-Node](https://github.com/nodejs/abi-stable-node) project also called
NAPI. The goal of this project is to ease the lives of native add-ons
developers, by providing a stable Node API which also guarantees stable ABI
across disparate Node versions. This allows native modules to just work across
different versions and flavors of Node.js without recompilations, reducing the
maintenance cost for module developers and thus improving compatibility.

Expand Down
125 changes: 73 additions & 52 deletions TTD-README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,63 +1,73 @@
# Diagnostic Tracing and Time Travel Debugging with Node-ChakraCore
In post-mortem debugging scenarios, developers frequently find themselves
In post-mortem debugging scenarios, developers frequently find themselves
hunting for failure clues (e.g. error text) in the log files and then searching
for those clues in their code. Once the log statement is found in the source code,
the developer is often left to re-construct the context of the error.
for those clues in their code. Once the log statement is found in the source
code, the developer is often left to re-construct the context of the error.

The cutting edge diagnostic capabilities in Node-ChakraCore allows developers to
look at the faulting code within the full fidelity of the debugger with all the
runtime context preserved, enabling them to deeply inspect the code as it was during
the original execution. Node-Chakracore has been extended with a suite of such features
to support tracing and reproducing program executions and a range of updates to improve
the time-travel debugging experience.
The cutting edge diagnostic capabilities in Node-ChakraCore allows developers to
look at the faulting code within the full fidelity of the debugger with all the
runtime context preserved, enabling them to deeply inspect the code as it was
during the original execution. Node-Chakracore has been extended with a suite of
such features to support tracing and reproducing program executions and a range
of updates to improve the time-travel debugging experience.

This project is being developed in the open and we are always happy to get feedback, bug reports,
functionality requests, and pull-requests from the community.
This project is being developed in the open and we are always happy to get
feedback, bug reports, functionality requests, and pull-requests from the
community.

## Diagnostic Tracing
Reproducing issues that depend on a specific interleaving of callbacks, specifics of
a server configuration or users system, or transient network/file-system behavior can be
challenging. To help simplify the process we have updated Node-ChakraCore with a suite
of **diagnostic tracing** features. These features allow you to record an application
execution using the `--record` flag and, then when any of the conditions listed below
occur, a diagnostic trace is written out to disk (with the location printed to
`stderr`).
Reproducing issues that depend on a specific interleaving of callbacks,
specifics of a server configuration or users system, or transient
network/file-system behavior can be challenging. To help simplify the process we
have updated Node-ChakraCore with a suite of **diagnostic tracing** features.
These features allow you to record an application execution using the `--record`
flag and, then when any of the conditions listed below occur, a diagnostic trace
is written out to disk (with the location printed to `stderr`).

Default trace emit events:
- Unhandled exceptions *always* emit a trace.
- Exit with a non-zero exit code *always* emits a trace.
- Failed `asserts` *probabilistically* emit a trace with a backoff to prevent overloading.
- Calls to `console.error` and `console.warn` *probabilistically* emit a trace with a backoff to prevent overloading.
- Failed `asserts` *probabilistically* emit a trace with a backoff to prevent
overloading.
- Calls to `console.error` and `console.warn` *probabilistically* emit a trace
with a backoff to prevent overloading.
- A `SIGINT` signal will *always* emit a trace.

When we run with our remote-file server [demo](https://github.com/mrkmarron/RFSDemoJS) with the record flag and
hit a bug in the file I/O code (followed by crtl-c on the command line) we get the output shown below.
When we run with our remote-file server
[demo](https://github.com/mrkmarron/RFSDemoJS) with the record flag and hit a
bug in the file I/O code (followed by crtl-c on the command line) we get the
output shown below.

![Running node with --record flag and two trace output events.](doc/ttd_assets/TraceSnap.png)

Once written to disk these trace directories can be used locally or copied to another machine
for later analysis and debugging.
Once written to disk these trace directories can be used locally or copied to
another machine for later analysis and debugging.

The animation below shows us launching the `TraceDebug` configuration in the VSCode debugger with the trace
directory argument set to the `emitOnSigInt` trace (written after seeing the file not found error).
When the trace hits the point where it raised and triggered for the error message write it will break into the debugger
allowing us to inspect local variables, the call stack and, set a breakpoint where the callback that received
the I/O error was registered. Then we reverse-execute back-in-time to this callback registration and can
inspect local variables as well as the full call stack as they existed then.
The animation below shows us launching the `TraceDebug` configuration in the
VSCode debugger with the trace directory argument set to the `emitOnSigInt`
trace (written after seeing the file not found error). When the trace hits the
point where it raised and triggered for the error message write it will break
into the debugger allowing us to inspect local variables, the call stack and,
set a breakpoint where the callback that received the I/O error was registered.
Then we reverse-execute back-in-time to this callback registration and can
inspect local variables as well as the full call stack as they existed then.

![Replay debugging with the --replay-debug flag and TTD.](doc/ttd_assets/TTDTrace.gif)

If desired we can single step-back through other statements as well or execute forward again, seeing the
exact set of statements and variable values that existed during the original execution, until we have
all the information we need to understand the problem.
If desired we can single step-back through other statements as well or execute
forward again, seeing the exact set of statements and variable values that
existed during the original execution, until we have all the information we need
to understand the problem.

## Time-Travel Debugging
## Time-Travel Debugging

TTD functionality is available in Node-ChakraCore and is supported by
[VSCode](https://code.visualstudio.com/). You can use VSCode to debug diagnostic
TTD functionality is available in Node-ChakraCore and is supported by
[VSCode](https://code.visualstudio.com/). You can use VSCode to debug diagnostic
traces even if you don't have the project sources available. This is done by:
- Creating an empty `dummy.js` file in the trace directory.
- Adding the following configuration into your `.vscode\launch.json` configuration file.
- Adding the following configuration into your `.vscode\launch.json`
configuration file.

```json
{
"name": "Trace Debug",
Expand All @@ -71,7 +81,7 @@ traces even if you don't have the project sources available. This is done by:
"runtimeArgs": [
"run",
"chakracore-nightly",
"--nolazy",
"--nolazy",
"--break-first",
"--replay-debug=./"
],
Expand All @@ -83,29 +93,40 @@ traces even if you don't have the project sources available. This is done by:
To get started with diagnostic tracing and TTD you will need the following:

- Install [Node-ChakraCore](https://github.com/nodejs/node-chakracore/releases)
- (Recommended) install [NVS](https://github.com/jasongin/nvs/blob/master/README.md) which is a cross-platform tool for switching between different versions and forks of Node.js and will allow you to easily switch between Node-ChakraCore and other Node.js versions. Once NVS is installed simply enter the following commands in the console:

- (Recommended) install
[NVS](https://github.com/jasongin/nvs/blob/master/README.md) which is a
cross-platform tool for switching between different versions and forks of
Node.js and will allow you to easily switch between Node-ChakraCore and
other Node.js versions. Once NVS is installed simply enter the following
commands in the console:

```console
$ nvs remote chakracore-nightly https://nodejs.org/download/chakracore-nightly/
$ nvs add chakracore-nightly/latest
$ nvs use chakracore-nightly
```
- (Manual) Download the build for your platform/architecture and manually add the location of the binaries to your path.

- (Manual) Download the build for your platform/architecture and manually
add the location of the binaries to your path.
- Install [VSCode](https://code.visualstudio.com/) using the latest installer.

## Sample Program
The code for the Remote File System sample demo'ed at NodeInteractive is available
[here](https://github.com/mrkmarron/RFSDemoJS).
The code for the Remote File System sample demo'ed at NodeInteractive is
available [here](https://github.com/mrkmarron/RFSDemoJS).

You can clone the repo to a location of your choice and `npm install` the dependencies. Once
you launch the application it will serve up the contents of the folder `testdata` on port 3000. The
application is designed to intermittently rename the files `hello_world.js <-> helloWorld.js`
in the background. So, as shown in the screenshot above, a warn trace can be triggered by interacting
with the application and clicking on this file at various times. You can always trigger a sigint
trace via crtl-c at the command line.
You can clone the repo to a location of your choice and `npm install` the
dependencies. Once you launch the application it will serve up the contents of
the folder `testdata` on port 3000. The application is designed to
intermittently rename the files `hello_world.js <-> helloWorld.js` in the
background. So, as shown in the screenshot above, a warn trace can be triggered
by interacting with the application and clicking on this file at various times.
You can always trigger a sigint trace via crtl-c at the command line.

Once this SIGINT trace is written it can be replay debugged in VSCode using the `TraceDebug` launch configuration and you can change the path if you want to debug other trace files that are written.
Once this SIGINT trace is written it can be replay debugged in VSCode using the
`TraceDebug` launch configuration and you can change the path if you want to
debug other trace files that are written.

## Feedback
Please let us know on our [issues page](https://github.com/nodejs/node-chakracore/issues) if
you have any question or comment.
Please let us know on our
[issues page](https://github.com/nodejs/node-chakracore/issues) if you have any
question or comment.
Loading