Skip to content

Dragonwell 21 AI‐Extension User Guide

Jump to bottom
MaxXing edited this page Mar 10, 2026 · 1 revision

Overview

Alibaba Dragonwell 21 AI-Extension is a production-grade downstream distribution of OpenJDK developed based on Dragonwell 21 Extended Edition. The AI-Extension is deeply optimized for AI applications. Through three core technologies: Native Acceleration, Hot Code Reordering, and JTune Intelligent Tuning, it helps enterprise customers maximize the performance of Java applications in AI scenarios.

Quick Start

Background on Java Scenario Acceleration

Supporting the Alibaba Cloud PaaS platform and numerous internal Java applications of Alibaba Group, the JDK team has accumulated multiple optimization methods. Dragonwell AI-Extension outputs these internal JDK optimizations as plugins, allowing more users to utilize Alibaba's optimization technologies and reducing the cognitive load of usage.

Scenario acceleration mainly comes in two forms:

  1. For specific applications such as ElasticSearch and Spark, pre-generated optimized methods are used to replace JIT compilation for known time-consuming methods, directly obtaining the best generated code.

  2. Enabling Dragonwell-specific optimizations, such as hot/cold code separation features. This reduces the use of unconventional JVM parameters and simplifies usage.

Applicable Scenarios

Alibaba Dragonwell 21 AI-Extension is suitable for the following scenarios:

  1. AI Vector Search & RAG Scenarios: For customers building enterprise-level intelligent knowledge bases, document assistants, intelligent Q&A, and other RAG applications, the AI-Extension can combine various technologies to comprehensively improve the operational efficiency of underlying components such as Elasticsearch.

  2. Big Data Analysis & Feature Engineering: For customers who need to process massive data, perform complex feature engineering, and data analysis, the AI-Extension can systematically optimize performance bottlenecks in big data frameworks such as Spark.

  3. Large Complex Systems like Intelligent Driving: For core systems with large codebases and dispersed runtime hotspots, such as intelligent driving and high-definition maps, the AI-Extension can effectively optimize Code Cache efficiency.

  4. Scenarios Pursuing Ultimate O&M Efficiency: For enterprises hoping to reduce JVM tuning costs and improve O&M automation levels, the AI-Extension can integrate with the AIOps system, transforming the JVM from a black box requiring passive tuning into a runtime capable of active introspection and intelligent interaction with external systems.

Installation and Integration

Dragonwell AI-Extension is an extension of Alibaba Dragonwell JDK, itself based on Dragonwell 21.0.8.0.8 or later versions. To install the latest AI Extension package, you can use the following command:

yum install java-21-alibaba-dragonwell-ai-extension

Usage

AI-Extension optimizations are mainly based on our open-source Dragonwell 21 product (version 21.0.8.0.8 and later), and currently support two parameters:

  • -XX:+UseAIExtension: This parameter is used to enable AI-Extension capabilities. It is currently a preview feature and needs to be used with the -XX:+UnlockExperimentalVMOptions option. As the system matures, this option will become a formal feature in subsequent versions.
  • -XX:AIExtensionUnit=xxx: This parameter can be used to load specific acceleration libraries for different scenarios.

For example, to accelerate ElasticSearch 8.17, users can add the following parameters:

-XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=es_8.17

Some components require additional parameters for control, for example, hot code can use parameters to specify the size of the hot code cache. In this case, additional parameters can be set by adding ?param1=val1:param2=val2 after the acceleration library name:

-XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=hotcode_1.0?hotcode_size=2m

As needed, users can also use multiple -XX:AIExtensionUnit parameters to enable multiple acceleration libraries simultaneously. For example, use the following options to enable both Spark optimization and hot code optimization:

-XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=spark_4.0 -XX:AIExtensionUnit=hotcode_1.0?mode=run

Acceleration Scenario Usage Guide

Elasticsearch
Applicable Version Elasticsearch 8.17
Architecture x86_64 (Requires AVX-512 instruction set support)
Optimization Features Algorithm Vectorization

Add the following parameters to the Java startup command:

java -XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=es_8.17 ..

Spark
Applicable Version Spark 4.0
Architecture x86_64
Optimization Features Algorithm Optimization

Add the following parameters to the Java startup command:

java -XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=spark_4.0 ..

Hot Code Reordering
Architecture x86_64/aarch64
Optimization Features Collect hotspots, centrally distribute hot methods

Hot code optimization requires two steps:

  1. Collect Hotspots

    Parameters that can be added when using the plugin:

    • mode: Enables the running mode of the plugin, there are trace (hotspot collection) and run (actual execution).
    • hotcode_size: Estimated hot code size. The default value of this parameter is related to the architecture, for example, it is 2m on aarch64.
    • start_time: How long after the Java process starts to begin collection, default value 5 minutes (5m).
    • duration: Collection duration, default value 10 minutes (10m).
    • output_file: Path to the generated hot code configuration file, default value hotcode.json.

    Example startup command for collecting hotspots:

    java -XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=hotcode_1.0?mode=trace:hotcode_size=2m:start_time=1m:duration=10m:output_file=app.json ..

    Concise version (using default configuration) command:

    java -XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=hotcode_1.0?mode=trace ..

  2. Actual Execution

    After collecting hotspots and generating hotspot code configuration files, the Java process can be restarted to optimize the JVM code layout.

    Plugin Parameter Description

    • mode: Enables the running mode of the plugin, there are trace (hotspot collection) and run (actual execution).
    • hotcode_size: Estimated hot code size. The default value of this parameter is related to the architecture, for example, it is 2m on aarch64.
    • input_file: Path to the hot code configuration file generated in hotspot collection mode, default value hotcode.json.

    Example startup command for actual execution:

    java -XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=hotcode_1.0?mode=run:hotcode_size=2m:input_file=app.json ..

    Concise version (using default configuration) command:

    java -XX:+UnlockExperimentalVMOptions -XX:+UseAIExtension -XX:AIExtensionUnit=hotcode_1.0?mode=run ..

JTune Intelligent Tuning

JTune is a powerful tool included in the AI-Extension. Different from traditional fixed-rule tuning, JTune has a built-in machine learning model that can automatically explore the vast JVM parameter combination space. Through a "Sample-Adjust-Verify" closed-loop feedback, it finds the optimal parameter configuration for your specific application and hardware environment.

JTune currently supports intelligently adjusting two parameters of G1 GC: G1NewSizePercent and G1MaxNewSizePercent. By controlling the Young Generation ratio, it improves throughput while maintaining RT as much as possible. In addition, JTune also supports intelligently recommending Java heap size based on GC behavior, i.e., the value of the -Xmx parameter.

JTune Usage Method:

  1. Configure the runtime environment. JTune depends on Python's machine learning libraries, so the following runtime environment is required:

    • Python 3.12.x: JTune compiles Python code into C code based on Cython, so the Python version must strictly comply with 3.12.x.
    • scikit-learn==1.7.1
    • pandas==2.3.2
    • matplotlib==3.10.5
    • mkl==2023.1.0
    • mkl-service==2.4.0
    • mkl_fft==1.3.11
    • mkl_random==1.2.8
    • optuna==4.2.1

    JTune will automatically detect whether the current environment meets the requirements during execution. If not, it will prompt the user to configure the environment.

    To simplify user operations, we provide a one-click environment installation script: [Dragonwell21_HOME]/lib/ai-ext/jtune/setup_conda.sh. Here [Dragonwell21_HOME] refers to the root directory of the Dragonwell 21 AI-Extension version JDK. After preparing conda, users only need to execute this script to complete all work for virtual environment creation and dependency library installation.

  2. Obtain application GC sampling data. JTune supports two data sources: JFR and GC logs. Enable JFR by setting Java application startup parameters, or output GC logs.

  3. After obtaining the sampling file, execute the command jtune --profile=[sampling file] --feature=G1GC[:ML parameters], wait patiently for a few minutes, and you will get the recommended GC parameters.

    • Sampling file: Can be a JFR file, such as xxx.jfr; or a GC log file, such as xxx-gc.log. Please note that the file type must match the extension.
    • Machine Learning parameters: Parameters for JTune to adjust machine learning behavior, separated by commas. e.g., --feature=G1GC:a=xxx,b=xxx,c=xxx. Available parameters include:
      • window-coefficient: Size of windowed data during preprocessing. Indicates the window size as a multiple of the average GC interval, default is 5. When sampled GC data is scarce, this parameter can be lowered to obtain more training data.
      • window-slide-ratio: The ratio of the window slide distance to the window size during preprocessing, a decimal in the range (0,1], default is 0.5. When sampled GC data is scarce, this parameter can be lowered to obtain more training data.
      • begin and end: You can intercept part of the data by setting the time points for begin and end. Both parameters are relative to the time of the first GC in the sampling data, in milliseconds.
      • png: Visualize the sampled GC data and tuning results as png images output, saved to the path specified by this parameter.
      • log-path: Tuning log path. Tuning logs are saved by default in the $HOME/jtune_logs directory, the log location can be changed via this parameter.

Compatibility and Support

Alibaba Dragonwell 21 AI-Extension is developed based on Dragonwell 21 Extended Edition. Dragonwell 21 Extended Edition is a downstream distribution of OpenJDK 21. You can directly use the AI-Extension to run existing JDK 21 applications without any code adaptation or migration.

Alibaba Dragonwell 21 AI-Extension provides Long-Term Support (LTS), and the maintenance cycle remains synchronized with OpenJDK: we will release updated versions every quarter. During this period, Alibaba Cloud will continue to provide performance optimization and security maintenance services for Dragonwell 21, so you can use it with confidence.

Clone this wiki locally