[GR-48794] Updated Insight documentation after Truffle unchained changes.

PullRequest: graal/15652

Author: entlicher

docs/tools/insight/Insight-Manual.md

@@ -41,14 +41,16 @@ Create a `source-tracing.js` script with following content:
 
 ```js
 insight.on('source', function(ev) {
-    print(`Loading ${ev.characters.length} characters from ${ev.name}`);
+    if (ev.characters) {
+        print(`Loading ${ev.characters.length} characters from ${ev.name}`);
+    }
 });
 ```
 Run it with GraalVM's `node` launcher adding the `--insight` instrument option.
 Observe what scripts are being loaded and evaluated:
 
 ```bash
-graalvm/bin/node --js.print --insight=source-tracing.js -e "print('The result: ' + 6 * 7)" | tail -n 10
+./bin/node --js.print --experimental-options --insight=source-tracing.js -e "print('The result: ' + 6 * 7)" | tail -n 10
 Loading 29938 characters from url.js
 Loading 345 characters from internal/idna.js
 Loading 12642 characters from punycode.js
@@ -77,6 +79,7 @@ var map = new Map();
 
 function dumpHotness() {
     print("==== Hotness Top 10 ====");
+    var count = 10;
     var digits = 3;
     Array.from(map.entries()).sort((one, two) => two[1] - one[1]).forEach(function (entry) {
         var number = entry[1].toString();
@@ -85,7 +88,7 @@ function dumpHotness() {
         } else {
             number = Array(digits - number.length + 1).join(' ') + number;
         }
-        if (number > 10) print(`${number} calls to ${entry[0]}`);
+        if (count-- > 0) print(`${number} calls to ${entry[0]}`);
     });
     print("========================");
 }
@@ -110,26 +113,19 @@ The latter is executed when the `node` process execution is over (registered via
 Invoke the program:
 
 ```bash
-graalvm/bin/node --js.print --insight=function-hotness-tracing.js -e "print('The result: ' + 6 * 7)"
+./bin/node --js.print --experimental-options --insight=function-hotness-tracing.js -e "print('The result: ' + 6 * 7)"
 The result: 42
 ==== Hotness Top 10 ====
-543 calls to isPosixPathSeparator
-211 calls to E
-211 calls to makeNodeErrorWithCode
-205 calls to NativeModule
-198 calls to uncurryThis
-154 calls to :=>
-147 calls to nativeModuleRequire
-145 calls to NativeModule.compile
- 55 calls to internalBinding
- 53 calls to :anonymous
- 49 calls to :program
- 37 calls to getOptionValue
- 24 calls to copyProps
- 18 calls to validateString
- 13 calls to copyPrototype
- 13 calls to hideStackFrames
- 13 calls to addReadOnlyProcessAlias
+516 calls to isPosixPathSeparator
+311 calls to :=>
+269 calls to E
+263 calls to makeNodeErrorWithCode
+159 calls to :anonymous
+157 calls to :program
+ 58 calls to getOptionValue
+ 58 calls to getCLIOptionsFromBinding
+ 48 calls to validateString
+ 43 calls to hideStackFrames
 ========================
 ```
 
@@ -162,7 +158,7 @@ Note: Make sure the Ruby support is enabled. See [Polyglot Programming guide](..
 Apply the JavaScript instrument to the Ruby program. Here is what you should see:
 
 ```bash
-graalvm/bin/ruby --polyglot --insight=source-trace.js helloworld.rb
+./bin/ruby --polyglot --insight=source-trace.js helloworld.rb
 JavaScript instrument observed load of helloworld.rb
 Hello from GraalVM Ruby!
 ```
@@ -195,7 +191,7 @@ Run it on top of [sieve.js](https://github.com/oracle/graal/blob/5ec71a206aa4220
 It is a sample script which uses a variant of the Sieve of Erathostenes to compute one hundred thousand of prime numbers:
 
 ```bash
-graalvm/bin/js --insight=function-tracing.js sieve.js | grep -v Computed
+./bin/js --insight=function-tracing.js sieve.js | grep -v Computed
 Just called :program as 1 function invocation
 Just called Natural.next as 17 function invocation
 Just called Natural.next as 33 function invocation
@@ -251,7 +247,7 @@ insight.on("enter", onEnter, Roots())
 Apply this script to [agent-fib.js](https://github.com/oracle/graal/blob/5ec71a206aa422078ac21be9949f8eb8918b3d3c/vm/tests/all/agentscript/agent-fib.js){:target="_blank"} using the following command:
 
 ```bash
-`js --polyglot --insight=agent.py agent-fib.js`
+`./bin/js --polyglot --insight=agent.py agent-fib.js`
 ```
 
 Note: Make sure the Python support is enabled. See [Polyglot Programming guide](../../reference-manual/polyglot-programming.md).
@@ -277,7 +273,7 @@ puts("Ruby: Hooks are ready!")
 Launch a Node.js application and instrument it with the Ruby script:
 
 ```bash
-graalvm/bin/node --js.print --experimental-options --polyglot --insight=source-tracing.rb agent-fib.js
+./bin/node --js.print --experimental-options --polyglot --insight=source-tracing.rb agent-fib.js
 Ruby: Initializing GraalVM Insight script
 Ruby: Hooks are ready!
 Ruby: observed loading of node:internal/errors
@@ -316,7 +312,7 @@ insight.on("enter", -> (ctx, frame) {
 
 The above Ruby script example prints out value of variable `n` when a function `minusOne` in the [agent-fib.js](https://github.com/oracle/graal/blob/5ec71a206aa422078ac21be9949f8eb8918b3d3c/vm/tests/all/agentscript/agent-fib.js){:target="_blank"} program is called:
 ```bash
-graalvm/bin/node --js.print --experimental-options --polyglot --insight=agent.rb agent-fib.js
+./bin/node --js.print --experimental-options --polyglot --insight=agent.rb agent-fib.js
 minusOne 4
 minusOne 3
 minusOne 2
@@ -343,7 +339,7 @@ cat("R: Hooks are ready!\n")
 Use it to trace a `test.R` program:
 
 ```bash
-graalvm/bin/Rscript --insight=agent-r.R test.R
+./bin/Rscript --insight=agent-r.R test.R
 R: Initializing GraalVM Insight script
 R: Hooks are ready!
 R: observed loading of test.R
@@ -360,14 +356,14 @@ Take, for examle, a long running program like [sieve.c](https://github.com/oracl
 First, execute the program on GraalVM:
 
 ```bash
-export TOOLCHAIN_PATH=`graalvm/bin/lli --print-toolchain-path`
+export TOOLCHAIN_PATH=`.../bin/lli --print-toolchain-path`
 ${TOOLCHAIN_PATH}/clang agent-sieve.c -lm -o sieve
-graalvm/bin/lli sieve
+./bin/lli sieve
 ```
 
 The GraalVM `clang` wrapper adds special options instructing the regular `clang` to keep the LLVM bitcode information in the `sieve` executable along the normal native code.
 The GraalVM's `lli` interpreter can then use the bitcode to interpret the program at full speed.
-By the way, compare the result of direct native execution via `./sieve` and interpreter speed of `graalvm/bin/lli sieve`.
+By the way, compare the result of direct native execution via `./sieve` and interpreter speed of `./bin/lli sieve`.
 It should show quite good results as for an interpreter.
 
 Now focus on breaking the endless loop. You can do it with this JavaScript `agent-limit.js` Insight script:
@@ -389,7 +385,7 @@ The script counts the number of invocations of the C `nextNatural` function and
 Run the program as:
 
 ```bash
-graalvm/bin/lli --polyglot --insight=agent-limit.js sieve
+./bin/lli --polyglot --insight=agent-limit.js sieve
 Computed 97 primes in 181 ms. Last one is 509
 GraalVM Insight: nextNatural method called 1000 times. enough!
         at <js> :anonymous(<eval>:7:117-185)
@@ -414,7 +410,7 @@ insight.on('enter', function(ctx, frame) {
 Print out a message everytime a new prime is added into the filter list:
 
 ```bash
-graalvm/bin/lli --polyglot --insight=agent-limit.js sieve | head -n 3
+./bin/lli --polyglot --insight=agent-limit.js sieve | head -n 3
 found new prime number 2
 found new prime number 3
 found new prime number 5
@@ -451,7 +447,7 @@ print("Two is the result " + fib(3));
 When the instrument is stored in a `fib-trace.js` file and the actual code in `fib.js`, then invoking following command yields detailed information about the program execution and parameters passed between function invocations:
 
 ```bash
-graalvm/bin/node --js.print --insight=fib-trace.js fib.js
+./bin/node --js.print --experimental-options --insight=fib-trace.js fib.js
 fib for 3
 fib for 2
 fib for 1
@@ -539,7 +535,7 @@ insight.on('enter', function(ctx, frame) {
 ```
 That gives us:
 ```bash
-graalvm/bin/js --insight=distance-trace.js distance.js
+./bin/js --insight=distance-trace.js distance.js
 Squares: 9, 16
 Loop var i = 0
 Loop var i = 1
@@ -577,7 +573,7 @@ Then it removes the probes using `insight.off` and invokes the actual `initializ
 The script can be run with:
 
 ```js
-graalvm/bin/node --js.print --insight=agent-require.js yourScript.js
+./bin/node --js.print --experimental-options --insight=agent-require.js yourScript.js
 ```
 
 This initialization sequence is known to work on GraalVM's `node` version 12.10.0 launched with the main `yourScript.js` parameter.
@@ -615,7 +611,7 @@ The `term.js` instrument waits for a call to `log` function with message `are` a
 As a result one gets:
 
 ```bash
-graalvm/bin/js --polyglot --insight=term.js seq.js
+./bin/js --polyglot --insight=term.js seq.js
 Hello GraalVM Insight!
 How
 great you are!
@@ -700,7 +696,7 @@ Repeating the computation fifty times gives the runtime a chance to warm up and
 Here is the optimal run:
 
 ```bash
-graalvm/bin/js sieve.js | grep -v Computed
+./bin/js sieve.js | grep -v Computed
 Hundred thousand prime numbers in 75 ms
 Hundred thousand prime numbers in 73 ms
 Hundred thousand prime numbers in 73 ms
@@ -709,7 +705,7 @@ Hundred thousand prime numbers in 73 ms
 Now compare it to execution time when running with the GraalVM Insight script enabled:
 
 ```bash
-graalvm/bin/js --insight=function-count.js sieve.js  | grep -v Computed
+./bin/js --insight=function-count.js sieve.js  | grep -v Computed
 Hundred thousand prime numbers in 74 ms
 Hundred thousand prime numbers in 74 ms
 Hundred thousand prime numbers in 75 ms
@@ -739,7 +735,7 @@ function Filter(number) {
 First, test the behavior by invoking the computation fifty times and measuring time it takes to finish the last round:
 
 ```bash
-graalvm/bin/js -e "var count=50" --file sieve.js | grep Hundred | tail -n 1
+./bin/js -e "var count=50" --file sieve.js | grep Hundred | tail -n 1
 Hundred thousand prime numbers in 73 ms
 ```
 
@@ -775,7 +771,7 @@ When the main loop in `measure` is over, e.g., there are hundred thousand prime
 Now try the following:
 
 ```bash
-graalvm/bin/js  -e "var count=50" --insight=sieve-filter1.js --file sieve.js | grep Hundred | tail -n 2
+./bin/js  -e "var count=50" --insight=sieve-filter1.js --file sieve.js | grep Hundred | tail -n 2
 Hundred thousand prime numbers from 2 to 1299709 has sum 62260698721
 Hundred thousand prime numbers in 74 ms
 ```
@@ -847,7 +843,7 @@ Save the code snippet as a `dump.js` file.
 Get the [sieve.js](https://github.com/oracle/graal/blob/5ec71a206aa422078ac21be9949f8eb8918b3d3c/vm/benchmarks/agentscript/sieve.js){:target="_blank"} file and launch it as:
 
 ```bash
-graalvm/bin/js --insight=dump.js --heap.dump=dump.hprof --file sieve.js
+./bin/js --insight=dump.js --heap.dump=dump.hprof --file sieve.js
 ```
 
 ![Heap Stack](img/Insight-HeapStack.png)

docs/tools/insight/Insight-Tracing.md

@@ -14,7 +14,7 @@ The following examples will demonstrate the tracing capabilities with GraalVM In
 To start, install the Jaeger's client side instrumentation library for Node.js:
 
 ```bash
-graalvm/bin/npm install [email protected]
+./bin/npm install [email protected]
 ```
 
 Now you can use the [OpenTracing API](https://github.com/opentracing/opentracing-javascript) provided by the `jaeger-client` module in your instrument `agent.js` via the `tracer` object (once it becomes available, it will discussed later in this guide):
@@ -157,7 +157,7 @@ docker run -d --name jaeger \
 -p 5778:5778   -p 16686:16686   -p 14268:14268   -p 9411:9411 \
 jaegertracing/all-in-one:latest
 
-graalvm/bin/node --insight=agent.js server.js
+./bin/node --insight=agent.js server.js
 Providing Jaeger object to the agent
 agent: Jaeger tracer obtained
 Initializing Jaeger Tracer with RemoteReporter and ConstSampler(always)

docs/tools/insight/README.md

@@ -27,12 +27,14 @@ To learn about Insight on versions 20.0 and 19.3, proceed [here](https://github.
 1. Create a simple _source-tracing.js_ script with the following content:
 ```javascript
 insight.on('source', function(ev) {
-    print(`Loading ${ev.characters.length} characters from ${ev.name}`);
+    if (ev.characters) {
+        print(`Loading ${ev.characters.length} characters from ${ev.name}`);
+    }
 });
 ```
-2. Having set `JAVA_HOME` to the GraalVM home directory, start the `node` launcher with the `--insight` tool and observe what scripts are being loaded and evaluated:
+2. Having installed the [Node.js runtime](https://github.com/oracle/graaljs/blob/master/docs/user/NodeJS.md#nodejs-runtime), start the `node` launcher with the `--insight` tool and observe what scripts are being loaded and evaluated:
 ```shell
-$JAVA_HOME/bin/node --insight=source-tracing.js --js.print -e "print('The result: ' + 6 * 7)" | tail -n 10
+./bin/node --insight=source-tracing.js --js.print --experimental-options -e "print('The result: ' + 6 * 7)" | tail -n 10
 Loading 215 characters from internal/modules/esm/transform_source.js
 Loading 12107 characters from internal/modules/esm/translators.js
 Loading 1756 characters from internal/modules/esm/create_dynamic_module.js
@@ -55,6 +57,7 @@ var map = new Map();
 
 function dumpHotness() {
     print("==== Hotness Top 10 ====");
+    var count = 10;
     var digits = 3;
     Array.from(map.entries()).sort((one, two) => two[1] - one[1]).forEach(function (entry) {
         var number = entry[1].toString();
@@ -63,7 +66,7 @@ function dumpHotness() {
         } else {
             number = Array(digits - number.length + 1).join(' ') + number;
         }
-        if (number > 10) print(`${number} calls to ${entry[0]}`);
+        if (count-- > 0) print(`${number} calls to ${entry[0]}`);
     });
     print("========================");
 }
@@ -90,26 +93,19 @@ A table with names and counts of function invocations is printed out when the `n
 
 Invoke it as:
 ```shell
-$JAVA_HOME/bin/node --insight=function-hotness-tracing.js --js.print -e "print('The result: ' + 6 * 7)"
+./bin/node --insight=function-hotness-tracing.js --js.print --experimental-options -e "print('The result: ' + 6 * 7)"
 The result: 42
 ==== Hotness Top 10 ====
-543 calls to isPosixPathSeparator
-211 calls to E
-211 calls to makeNodeErrorWithCode
-205 calls to NativeModule
-198 calls to uncurryThis
-154 calls to :=>
-147 calls to nativeModuleRequire
-145 calls to NativeModule.compile
- 55 calls to internalBinding
- 53 calls to :anonymous
- 49 calls to :program
- 37 calls to getOptionValue
- 24 calls to copyProps
- 18 calls to validateString
- 13 calls to copyPrototype
- 13 calls to hideStackFrames
- 13 calls to addReadOnlyProcessAlias
+516 calls to isPosixPathSeparator
+311 calls to :=>
+269 calls to E
+263 calls to makeNodeErrorWithCode
+159 calls to :anonymous
+157 calls to :program
+ 58 calls to getOptionValue
+ 58 calls to getCLIOptionsFromBinding
+ 48 calls to validateString
+ 43 calls to hideStackFrames
 ========================
 ```
 
@@ -132,7 +128,7 @@ puts 'Hello from GraalVM Ruby!'
 ```
 3. Apply the JavaScript instrument to the Ruby program:
 ```shell
-$JAVA_HOME/bin/ruby --jvm --polyglot --insight=source-trace.js helloworld.rb
+./bin/ruby --polyglot --insight=source-trace.js helloworld.rb
 JavaScript instrument observed load of helloworld.rb
 Hello from GraalVM Ruby!
 ```
@@ -152,7 +148,7 @@ puts 'Ruby: Hooks are ready!'
 
 2. Launch a Node.js application and instrument it with the Ruby script:
 ```shell
-$JAVA_HOME/bin/node --jvm  --polyglot --insight=source-tracing.rb --js.print -e "print('With Ruby: ' + 6 * 7)" | grep Ruby
+./bin/node --polyglot --insight=source-tracing.rb -e "console.log('With Ruby: ' + 6 * 7)" | grep Ruby
 Ruby: Initializing GraalVM Insight script
 Ruby: Hooks are ready!
 Ruby: observed loading of internal/per_context/primordials.js
@@ -196,7 +192,7 @@ print("Two is the result " + fib(3));
 
 When the instrument is stored in a `fib-trace.js` file and the actual code is in `fib.js`, invoking the following command yields detailed information about the program execution and parameters passed between function invocations:
 ```shell
-$JAVA_HOME/bin/node --insight=fib-trace.js --js.print fib.js
+./bin/node --insight=fib-trace.js --js.print --experimental-options fib.js
 fib for 3
 fib for 2
 fib for 1