[GR-37636] Declarative position of insight context.

PullRequest: graal/11980

Author: entlicher

docs/tools/insight/Insight-Manual.md

@@ -24,6 +24,7 @@ This provides ultimate insights into execution and behavior of one's application
 - [Insight into C Code](#insight-into-c-code)
 - [Inspecting Values](#inspecting-values)
 - [Modifying Local Variables](#modifying-local-variables)
+- [Insight to a Specific Location](#insight-to-a-specific-location)
 - [Delaying Insight Initialization in Node.JS](#delaying-insight-initialization-in-nodejs)
 - [Handling Exceptions](#handling-exceptions)
 - [Intercepting and Altering Execution](#intercepting-and-altering-execution)
@@ -216,24 +217,38 @@ It is possible to write GraalVM Insight scripts in Python.
 Such insights can be applied to programs written in Python or any other language.
 
 Here is an example of a script that prints out value of variable `n` when a function `minusOne` is called.
-Save this code to the `agent-fib.js` file:
+Save this code to the `agent.py` file:
+
+```python
+def onEnter(ctx, frame):
+    print(f"minusOne {frame.n}")
+
+class At:
+    sourcePath = ".*agent-fib.js"
+
+class Roots:
+    roots = True
+    at = At()
+    rootNameFilter = "minusOne"
+
+insight.on("enter", onEnter, Roots())
+```
+This code uses a declarative specification of source location introduced in GraalVM 22.2. Use a dynamic `sourceFilter` with older GraalVM versions:
 
 ```python
 def onEnter(ctx, frame):
     print(f"minusOne {frame.n}")
 
 class Roots:
     roots = True
+    rootNameFilter = "minusOne"
 
     def sourceFilter(self, src):
         return src.name == "agent-fib.js"
 
-    def rootNameFilter(self, n):
-        return n == "minusOne"
-
 insight.on("enter", onEnter, Roots())
 ```
-Apply this script to, for example, a JavaScript application using the following command:
+Apply this script to [agent-fib.js](../../../vm/tests/all/agentscript/agent-fib.js) using the following command:
 
 ```bash
 `js --polyglot --insight=agent.py agent-fib.js`
@@ -257,35 +272,55 @@ insight.on("source", -> (env) {
   puts "Ruby: observed loading of #{env.name}"
 })
 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
+Ruby: Initializing GraalVM Insight script
+Ruby: Hooks are ready!
+Ruby: observed loading of node:internal/errors
+Ruby: observed loading of node:internal/util
+Ruby: observed loading of node:events
+....
+Ruby: observed loading of node:internal/modules/run_main
+Ruby: observed loading of <...>/agent-fib.js
+Three is the result 3
+```
 
+To track variable values, create `agent.rb` script:
+```ruby
+insight.on("enter", -> (ctx, frame) {
+    puts("minusOne #{frame.n}")
+}, {
+  roots: true,
+  rootNameFilter: "minusOne",
+  at: {
+    sourcePath: ".*agent-fib.js"
+  }
+})
+```
+This code uses a declarative specification of source location introduced in GraalVM 22.2. Use a dynamic `sourceFilter` with older GraalVM versions:
+```ruby
 insight.on("enter", -> (ctx, frame) {
     puts("minusOne #{frame.n}")
 }, {
   roots: true,
   rootNameFilter: "minusOne",
   sourceFilter: -> (src) {
-    return src.name == "agent-fib.js"
+    return src.name == Dir.pwd+"/agent-fib.js"
   }
 })
 ```
 
-The above Ruby script example prints out value of variable `n` when a function `minusOne` in the `agent-fib.js` program is called.
-Launch a Node.js application and instrument it with the Ruby script:
-
+The above Ruby script example prints out value of variable `n` when a function `minusOne` in the [agent-fib.js](../../../vm/tests/all/agentscript/agent-fib.js) program is called:
 ```bash
-graalvm/bin/node --js.print --polyglot --insight=agent-ruby.rb agent-fib.js
-Ruby: Initializing GraalVM Insight script
-Ruby: Hooks are ready!
-Ruby: observed loading of internal/per_context/primordials.js
-Ruby: observed loading of internal/per_context/setup.js
-Ruby: observed loading of internal/per_context/domexception.js
-....
-Ruby: observed loading of internal/modules/cjs/loader.js
-Ruby: observed loading of vm.js
-Ruby: observed loading of fs.js
-Ruby: observed loading of internal/fs/utils.js
-Ruby: observed loading of [eval]-wrapper
-Ruby: observed loading of [eval]
+graalvm/bin/node --js.print --experimental-options --polyglot --insight=agent.rb agent-fib.js
+minusOne 4
+minusOne 3
+minusOne 2
+minusOne 2
 Three is the result 3
 ```
 
@@ -462,6 +497,58 @@ GraalVM Insight `enter` and `return` hooks can only modify existing variables.
 They cannot introduce new ones.
 Attempts to do so yield an exception.
 
+## Insight to a Specific Location
+
+To get to variables at a specific code location, the `at` object may have not only one of the mandatory source specifications:
+a `sourcePath` property with the regular expression matching the source file path, or `sourceURI` property with string representation of the source URI.
+There can also be an optional `line` and/or `column` specified. Let's have a `distance.js` source file:
+```js
+(function(x, y) {
+    let x2 = x*x;
+    let y2 = y*y;
+    let d = Math.sqrt(x2 + y2);
+    for (let i = 0; i < d; i++) {
+        // ...
+    }
+    return d;
+})(3, 4);
+```
+
+Then we can apply following `distance-trace.js` insight script to get values of variables:
+```js
+insight.on('enter', function(ctx, frame) {
+    print("Squares: " + frame.x2 + ", " + frame.y2);
+}, {
+    statements: true,
+    at: {
+        sourcePath: ".*distance.js",
+        line: 4
+    }
+});
+
+insight.on('enter', function(ctx, frame) {
+    print("Loop var i = " + frame.i);
+}, {
+    expressions: true,
+    at: {
+        sourcePath: ".*distance.js",
+        line: 5,
+        column: 21
+    }
+});
+```
+That gives us:
+```bash
+graalvm/bin/js --insight=distance-trace.js distance.js
+Squares: 9, 16
+Loop var i = 0
+Loop var i = 1
+Loop var i = 2
+Loop var i = 3
+Loop var i = 4
+Loop var i = 5
+```
+
 ## Delaying Insight Initialization in Node.JS
 
 GraalVM Insight can be used in any GraalVM language runtime, including the `node` implementation.

docs/tools/insight/Insight-Tracing.md

@@ -40,7 +40,9 @@ let initialize = function(tracer) {
     }, {
         roots: true,
         rootNameFilter: 'emit',
-        sourceFilter: src => src.name === 'events.js'
+        at: {
+            sourcePath: '.*events.js'
+        }
     });
 
     insight.on('return', function(ctx, frame) {
@@ -54,7 +56,9 @@ let initialize = function(tracer) {
     }, {
         roots: true,
         rootNameFilter: 'end',
-        sourceFilter: src => src.name === '_http_outgoing.js'
+        at: {
+            sourcePath: '.*_http_outgoing.js'
+        }
     });
     console.log('agent: ready');
 };