- Latest (GraalVM for JDK 21)
- Dev Build
- GraalVM for JDK 21
- GraalVM for JDK 20
- GraalVM for JDK 17
- GraalVM 22.3
- GraalVM 22.2
- GraalVM 22.1
- GraalVM 22.0
- GraalVM 21.3
- Native Image
- Build Output
- Build Configuration
- Tracing Agent
- Native Image Compatibility and Optimization Guide
- Class Initialization in Native Image
- Static Native Images
- Native Image Options
- Native Image Hosted and Runtime Options
- Native Image C API
- Implementing Native Methods in Java with Native Image
- LLVM Backend for Native Image
- Debug Info Feature
- Points-to Analysis Reports
- Using System Properties in Native Images
- Profile-Guided Optimizations
- Memory Management at Image Run Time
- Generating Heap Dumps from Native Images
- JDK Flight Recorder with Native Image
- JCA Security Services on Native Image
- Dynamic Proxy on Native Image
- Java Native Interface (JNI) on Native Image
- Reflection on Native Image
- Accessing Resources in Native Images
- Logging on Native Image
- URL Protocols on Native Image
- Native Image ARM64 Support
- GraalVM Updater
- Languages References
- Embedding Reference
- Polyglot Programming
Points-to Analysis Reports
The points-to analysis produces two kinds of reports: analysis call tree and image object tree. This information is produced by an intermediate step in the image building process and represents the static analysis view of the call graph and heap object graph. These graphs are further transformed in the image building process before they are AOT compiled into the image and written into the image heap, respectively.
The call tree is a a breadth-first tree reduction of the call graph as seen by the points-to analysis.
The points-to analysis eliminates calls to methods that it determines cannot be reachable at runtime, based on the analysed receiver types.
It also completely eliminates invocations in unreachable code blocks, e.g., blocks guarded by a type check that always fails.
The call tree report is enabled using the
-H:+PrintAnalysisCallTree option and can be formatted either as a
TXT file (default) or as a set of
CSV files using the
When using the
TXT format a file with the following structure is generated:
VM Entry Points ├── entry <entry-method> id=<entry-method-id> │ ├── directly calls <callee> id=<callee-id> @bci=<invoke-bci> │ │ └── <callee-sub-tree> │ ├── virtually calls <callee> @bci=<invoke-bci> │ │ ├── is overridden by <overide-method-i> id=<overide-method-i-id> │ │ │ └── <callee-sub-tree> │ │ └── is overridden by <overide-method-j> id-ref=<overide-method-j-id> │ └── interfacially calls <callee> @bci=<invoke-bci> │ ├── is implemented by <implementation-method-x> id=<implementation-method-x-id> │ │ └── <callee-sub-tree> │ └── is implemented by <implementation-method-y> id-ref=<implementation-method-y-id> ├── entry <entry-method> id=<entry-method-id> │ └── <callee-sub-tree> └── ...
The tags between
> are expanded with concrete values, the rest is printed as presented.
The methods are formatted using
<qualified-holder>.<method-name>(<qualified-parameters>):<qualified-return-type> and are expanded until no more callees can be reached.
Since this is a tree reduction of the call graph each concrete method is expanded exactly once.
The tree representation inherently omits calls to methods that have already been explored in a different branch or previously on the same branch.
This restriction implicitly fixes the recursion problem.
To convey the information that is lost through tree reduction each concrete method is given a unique id.
Thus when a method is reached for the first time it declares an identifier as
Subsequent discoveries of the same method use an identifier reference to point to the previously expansion location:
id-ref=<method-id> are followed by a blank space to make it easy to search.
Each invoke is tagged with the invocation bci:
For invokes of inline methods the
<invoke-bci> is a list of bci values, separated with
->, enumerating the inline locations, backwards to the original invocation location.
When using the
CSV format a set of files containing raw data for methods and their relationships is generated.
The aim of these files is to enable this raw data to be easily imported into graph databases.
Graph databases can provide the following functionality:
- Sophisticated graphical visualization of the call tree graph that provide a different perspective compared to text-based formats.
- Ability to execute complex queries that can for example show a subset of the tree that causes certain code path to be included in the call tree analysis. This querying functionality is crucial in making big analysis call trees manageable.
The process to import the files into graph databases is specific to each database. Please follow the instructions provided by the graph database providers to find out how to import them.
Image object tree
The image object tree is an exhaustive expansion of the objects included in the native image heap.
The tree is obtained by a depth first walk of the native image heap object graph.
It is enabled using the
The roots are either static fields or method graphs that contain embedded constants.
The printed values are concrete constant objects added to the native image heap.
Produces a file with the structure:
Heap roots ├── root <root-field> value: │ └── <value-type> id=<value-id> toString=<value-as-string> fields: │ ├── <field-1> value=null │ ├── <field-2> toString=<field-2-value-as-string> (expansion suppressed) │ ├── <field-3> value: │ │ └── <field-3-value-type> id=<field-3-value-id> toString=<field-3-value-as-string> fields: │ │ └── <object-tree-rooted-at-field-3> │ ├── <array-field-4> value: │ │ └── <array-field-4-value-type> id=<array-field-4-value-id> toString=<array-field-4-value-as-string> elements (excluding null): │ │ ├── [<index-i>] <element-index-i-value-type> id=<element-index-i-value-id> toString=<element-index-i-value-as-string> fields: │ │ │ └── <object-tree-rooted-at-index-i> │ │ └── [<index-j>] <element-index-j-value-type> id=<element-index-j-value-id> toString=<element-index-j-value-as-string> elements (excluding null): │ │ └── <object-tree-rooted-at-index-j> │ ├── <field-5> value: │ │ └── <field-5-value-type> id-ref=<field-5-value-id> toString=<field-5-value-as-string> │ ├── <field-6> value: │ │ └── <field-6-value-type> id=<field-6-value-id> toString=<field-6-value-as-string> (no fields) │ └── <array-field-7> value: │ └── <array-field-7-value-type> id=<array-field-7-id> toString=<array-field-7-as-string> (no elements) ├── root <root-field> id-ref=<value-id> toString=<value-as-string> ├── root <root-method> value: │ └── <object-tree-rooted-at-constant-embeded-in-the-method-graph> └── ...
The tags between
> are expanded with concrete values, the rest is printed as presented.
The root fields are formatted using
The non-root fields are formatted using
The value types are formatted using
The root methods are formatted using
No-array objects are expanded for all fields (including null).
No-array objects with no fields are tagged with
Array objects are expanded for all non-null indexes:
Empty array objects or with all null elements are tagged with
Each constant value is expanded exactly once to compress the format.
When a value is reached from multiple branches it is expanded only the first time and given an identifier:
Subsequent discoveries of the same value use an identifier reference to point to the previously expansion location:
Suppressing expansion of values
Some values, such as
BigInteger and primitive arrays, are not expanded by default and marked with
All the other types are expanded by default.
To force the suppression of types expanded by default you can use
To force the expansion of types suppressed by default or through the option you can use
-H:ImageObjectTreeExpandTypes are specified
-H:ImageObjectTreeExpandTypes has precedence.
Similarly, some roots, such as
java.lang.Character$UnicodeBlock.map" that prints a lot of strings, are not expanded at all and marked with
(expansion suppressed) as well.
All the other roots are expanded by default.
To force the suppression of roots expanded by default you can use
To force the expansion of roots suppressed by default or through the option you can use
-H:ImageObjectTreeExpandRoots are specified
-H:ImageObjectTreeExpandRoots has precedence.
All the suppression/expansion options above accept a comma-separated list of patterns.
For types the pattern is based on the fully qualified name of the type and refers to the concrete type of the constants.
(For array types it is enough to specify the elemental type; it will match all the arrays of that type, of all dimensions.)
For roots the pattern is based on the string format of the root as described above.
The pattern accepts the
*<str>- the pattern exactly matches all entries that end with
<str>*- the pattern exactly matches all entries that start with
*<str>*- the pattern exactly matches all entries that contain
<str>- the pattern exactly matches all entries that are equal to
*- the pattern matches all entries
-H:ImageObjectTreeSuppressTypes=java.io.BufferedWriter- suppress the expansion of
-H:ImageObjectTreeSuppressTypes=java.io.BufferedWriter,java.io.BufferedOutputStream- suppress the expansion of
-H:ImageObjectTreeSuppressTypes=java.io.*- suppress the expansion of all
-H:ImageObjectTreeExpandTypes=java.lang.String- force the expansion of
-H:ImageObjectTreeExpandTypes=java.lang.String,java.math.BigInteger- force the expansion of
-H:ImageObjectTreeExpandTypes=java.lang.*- force the expansion of all
-H:ImageObjectTreeSuppressTypes=java.io.* -H:ImageObjectTreeExpandTypes=java.io.PrintStream- suppress the expansion of all
-H:ImageObjectTreeExpandTypes=*- force the expansion of objects of all types, including those suppressed by default
-H:ImageObjectTreeSuppressRoots="java.nio.charset.Charset.lookup(String)"- suppress the expansion of all constants embedded in the graph of
-H:ImageObjectTreeSuppressRoots=java.util.*- suppress the expansion of all roots that start with
-H:ImageObjectTreeExpandRoots=java.lang.Character$UnicodeBlock.map- force the expansion of
java.lang.Character$UnicodeBlock.mapstatic field root
-H:ImageObjectTreeSuppressRoots=java.util.* -H:ImageObjectTreeExpandRoots=java.util.Locale- suppress the expansion of all roots that start with
-H:ImageObjectTreeExpandRoots=*- force the expansion of all roots, including those suppressed by default
The reports are generated in the
reports subdirectory, relative to the image building directory.
When executing the
native-image executable the image build directory defaults to the working directory and can be modified using the
The call tree report name has the structure
call_tree_<image_name>_<date_time>.txt when using the
TXT format or, when using the
CSV format, the call tree reports’ names have the structure
CSV formatted call tree reports, symbolic links following the structure
call_tree_*.csv pointing to the latest call tree CSV reports are also generated.
The object tree report name has the structure:
The image name is the name of the generated image, which can be set with the
<date_time> is in the