[GR-50848] Add an embedding example to the Insight documentation.

PullRequest: graal/16341

docs/tools/insight/Insight-Embedding.md

@@ -10,8 +10,7 @@ permalink: /tools/graalvm-insight/embedding/
 ## Embedding Insight into Java
 
 GraalVM languages (languages implemented with the Truffle framework, i.e., JavaScript, Python, Ruby, R) can be embedded into custom Java applications via [Polyglot Context API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Context.html).
-GraalVM Insight can also be controlled via the same API.
-For example:
+GraalVM Insight can also be controlled via the same API. Like:
 
 ```java
 final Engine engine = context.getEngine();
@@ -21,8 +20,54 @@ AutoCloseable handle = access.apply(agentSrc);
 ```
 
 Obtain `Engine` for `Context` and ask for the `insight` instrument.
+<p>
 Then create `Source` with the GraalVM Insight script and apply it while obtaining its instrumentation handle.
 Use `handle.close()` to disable all the script's instrumentations when when no longer needed.
+For Example:
+
+```java
+Source instrument = Source.create("js", """
+    insight.on('return', function(ctx, frame) {
+        console.log(`Instrumented where = ${frame.where}`);
+    }, {
+        roots: true,
+        rootNameFilter: 'end',
+    });
+    """);
+Source script = Source.create("js", """
+    function end() {
+        var where = 'end';
+        console.log(where + ' invoked')
+    }
+    end();
+    """);
+try (Context context = Context.newBuilder().build()) {
+    @SuppressWarnings("unchecked")
+    Function<Source, AutoCloseable> insight = context.getEngine().getInstruments().get("insight").lookup(Function.class);
+
+    // run without instrumentation
+    context.eval(script);
+
+    // run with instrumentation
+    try (AutoCloseable handle = insight.apply(instrument)) {
+        context.eval(script);
+    }
+
+    // run without instrumentation
+    context.eval(script);
+}
+```
+
+See [Embedding Dependency Setup](../../reference-manual/embedding/embed-languages.md#dependency-setup). Add a dependency on `insight`:
+```
+<dependency>
+    <groupId>org.graalvm.polyglot</groupId>
+    <!-- Select tools: profiler, inspect, coverage, dap, tools -->
+    <artifactId>insight</artifactId>
+    <version>23.1.1</version>
+    <type>pom</type>
+</dependency>
+```
 
 ### Ignoring Internal Scripts
 

tools/src/org.graalvm.tools.insight/src/org/graalvm/tools/insight/Insight.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2020, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -36,8 +36,13 @@
  * {@codesnippet Embedding#apply}
  *
  * and then {@link Function#apply(java.lang.Object) evaluate} {@link org.graalvm.polyglot.Source}
- * scripts written in any language accessing the {@code agent} variable exposed to them. Use
- * {@link #VERSION following API} when dealing with the {@code insight} variable:
+ * scripts written in any language accessing the {@code agent} variable exposed to them.
+ * <p>
+ * See an example at <a href=
+ * "https://www.graalvm.org/latest/tools/graalvm-insight/embedding/#embedding-insight-into-java">Embedding
+ * Insight into Java</a>.
+ *
+ * Use {@link #VERSION following API} when dealing with the {@code insight} variable:
  * <p>
  * {@codesnippet InsightAPI}
  *
@@ -79,16 +84,16 @@ private Insight() {
      * every {@link #ID Insight script} when properly registered into the virtual machine. A typical
      * way is to register your custom instrument is to use property
      * {@code truffle.class.path.append} when launching the virtual machine:
-     * 
+     *
      * <pre>
      * graalvm/bin/java -Dtruffle.class.path.append=meaningOfWorld.jar -jar app.jar
      * </pre>
-     * 
+     *
      * Take care when writing your {@link TruffleInstrument instruments} as they can alter many
      * aspects of program execution and aren't subject to any security sandbox. See
      * {@link TruffleInstrument} for more information about developing, using and registering
      * instruments.
-     * 
+     *
      * @since 21.0
      */
     public interface SymbolProvider {