Developers & Practitioners

Announcing native image support for Java Client Libraries — Optimize your short lived workloads

July 7, 2022

https://storage.googleapis.com/gweb-cloudblog-publish/images/native_imagessupport_heroimage.max-2200x2200.png

Aaron Wanjala

Java Developer Advocate

Cameron Balahan

Product Manager

We are excited to announce that Cloud Java Client Libraries now have built-in support for Native Image compilation!

Native Image technology enables you to compile your Java applications ahead-of-time and into a standalone executable. This results in several performance benefits, such as fast cold startup times and less upfront memory usage (as it doesn’t require a JVM).

However, Native Image compilation isn’t always compatible with some forms of Java code (resource loading, reflection) and requires extra configuration. With this launch, Cloud Client Libraries now come with the configuration that the libraries need for native image compilation, allowing users to compile their applications without additional configurations. It is also important to note that with this technology, you lose the JVM's run time optimizations, making native compilation best suited for short-lived workloads where quick startup and response time is key.

Performance Benefits

We conducted a performance comparison of an application built as a native image against the same application run with standard Java (17.0.3, Temurin) and noticed the following benefits.

https://storage.googleapis.com/gweb-cloudblog-publish/images/01_Average_startup_times_in_milliseconds.max-600x600.png

https://storage.googleapis.com/gweb-cloudblog-publish/images/02_Average_startup__first_request_times_in_m.max-600x600.png

The performance gap shown above is significant, especially when just comparing startup times. In this example, 87.65% of the native image start up times came in under 1 millisecond, which would make an enormous difference when aiming to optimize for cold start latency.

Memory Usage

Memory usage for the application compiled to a native image is also significantly smaller. We used the ps command to check the resident set size, which is the non-swapped physical memory that a task has used, and saw the following results:

https://storage.googleapis.com/gweb-cloudblog-publish/images/03_Resident_Set_Size_in_kilobytes.max-600x600.png

Getting Started

This section will walk you through running the Pub/Sub Storage Sample with native image compilation.

To demonstrate the performance benefits unlocked by the client library support of native image compilation we’ll build a sample application that makes use of the Pub/Sub and Storage client libraries, informed by this guide. Feel free to follow along on your own machine, or with the Cloud Shell.

Prerequisites

To reproduce the application that we used to gather the performance data above, you will need:

A Google Cloud project (with the Pub/Sub and Storage APIs enabled)
A Pub/Sub topic
A Storage bucket

Building the sample app

Start by generating our project with the following Maven goal:

This will generate a new Maven project that will serve as a reasonable starting point for our sample app.

Start by setting the maven compiler plugin’s release version to 17 (or later) and adding the client libraries as dependencies:

Add a class called ListPubSubNotifications in the same directory as as App.java:

This class will simply list any Pub/Sub notifications that are set up for a given Storage bucket.

Next, add another class in the same package called PublishWithErrorHandlerExample:

package com.mycompany.app;

import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.pubsub.v1.Publisher;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.protobuf.ByteString;
import com.google.pubsub.v1.PubsubMessage;
import com.google.pubsub.v1.TopicName;

import java.io.IOException;

import java.util.Date;
import java.util.concurrent.TimeUnit;

public class PublishWithErrorHandlerExample {

public static void publishWithErrorHandlerExample(String projectId, String topicId)
            throws IOException, InterruptedException {
        TopicName topicName = TopicName.of(projectId, topicId);
        Publisher publisher = null;

try {
            // Create a publisher instance with default settings bound to the topic
            publisher = Publisher.newBuilder(topicName).build();

String message = String.valueOf(new Date().getTime());

ByteString data = ByteString.copyFromUtf8(message);
            PubsubMessage pubsubMessage = PubsubMessage.newBuilder().setData(data).build();

// Once published, returns a server-assigned message id (unique within the topic)
            ApiFuture<String> future = publisher.publish(pubsubMessage);

// Add an asynchronous callback to handle success / failure
            ApiFutures.addCallback(
                    future,
                    new ApiFutureCallback<String>() {

@Override
                        public void onFailure(Throwable throwable) {
                            if (throwable instanceof ApiException) {
                                ApiException apiException = ((ApiException) throwable);
                                // details on the API exception
                                System.out.println(apiException.getStatusCode().getCode());
                                System.out.println(apiException.isRetryable());
                            }
                            System.out.println("Error publishing message : " + message);
                        }

@Override
                        public void onSuccess(String messageId) {
                            // Once published, returns server-assigned message ids (unique within the topic)
                            System.out.println("Published message ID: " + messageId);
                        }
                    },
                    MoreExecutors.directExecutor());
        } finally {
            if (publisher != null) {
                // When finished with the publisher, shutdown to free up resources.
                publisher.shutdown();
                publisher.awaitTermination(1, TimeUnit.MINUTES);
            }
        }
    }
}

This class will publish a timestamp message to a given topic, and handle exceptions in case of failure.

Finally, in App.java’s main function, add some logic to call the functions in both classes and keep track of startup/execution time:

package com.mycompany.app;

import java.io.IOException;
import java.lang.management.ManagementFactory;
import java.time.Duration;
import java.time.Instant;
import java.util.concurrent.TimeUnit;

public class App 
{
    private static final Instant INITIALIZATION_TIME = Instant.ofEpochMilli(ManagementFactory.getRuntimeMXBean().getStartTime());

private static final String projectId = "YOUR_PROJECT_ID";
    private static final String bucketName = "YOUR_BUCKET_NAME";
    private static final String topicId = "YOUR_TOPIC_ID";

public static void main(String... args) throws IOException, InterruptedException {
        final Duration startupTime = Duration.between(INITIALIZATION_TIME, Instant.now());
        ListPubSubNotifications.listPubSubNotifications(bucketName);
        final Duration timeToFirstRequest = Duration.between(INITIALIZATION_TIME, Instant.now());
        PublishWithErrorHandlerExample.publishWithErrorHandlerExample(projectId, topicId);

System.out.println("Startup time: " + startupTime.toMillis() + " ms, or " + TimeUnit.NANOSECONDS.toMicros(startupTime.toNanos()) + " microseconds");
        System.out.println("Time to finish first request: " + timeToFirstRequest.toMillis() + "ms");
        System.out.println("Shutting down. Total time elapsed: " + Duration.between(INITIALIZATION_TIME, Instant.now()).toMillis() + "ms");
    }
}

Now that the sample application is in place you are ready to configure the native image build.

Build configuration

Add the following `native-image` build profile to your pom.xml:

<profiles>
  <profile>
    <id>native-image</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.graalvm.buildtools</groupId>
          <artifactId>native-maven-plugin</artifactId>
          <version>0.9.11</version>
          <extensions>true</extensions>
          <executions>
            <execution>
              <id>build-native</id>
              <goals>
                <goal>build</goal>
              </goals>
              <phase>package</phase>
            </execution>
          </executions>
          <configuration>
            <mainClass>com.mycompany.app.App</mainClass>
          </configuration>
        </plugin>
      </plugins>
    </build>
  </profile>
  <profile>
    <id>regular-jar</id>
    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-assembly-plugin</artifactId>
          <executions>
            <execution>
              <phase>package</phase>
              <goals>
                <goal>single</goal>
              </goals>
              <configuration>
                <archive>
                  <manifest>
                    <mainClass>
                      com.mycompany.app.App
                    </mainClass>
                  </manifest>
                </archive>
                <descriptorRefs>
                  <descriptorRef>jar-with-dependencies</descriptorRef>
                </descriptorRefs>
              </configuration>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
  </profile>
</profiles>

This plugin and profile simplify the process of providing the native-image builder with the configuration it needs to build your application into a native image. Ensure that the `mainClass` parameter is correct for your application, and note that `buildArgs` can be used to pass options to the builder.

At this point, your app is ready to be built into a native image. There are, however, a few things worth keeping in mind with native-image’s ahead-of-time builds:

They take longer than equivalent just-in-time builds (approx. 5-10 minutes*)
They take quite a bit of memory (approx. 6-10GB*)

* values come from building this sample on the Cloud Shell’s e2-standard-4 machine type

To run the build, we will need to ensure that we have an appropriate JDK and the native-image builder. This process can be greatly simplified with the help of SDKMAN!.

Install the appropriate JDK distribution like GraalVM with the following command:

Then, inform sdkman to use this version in your current shell:

Next, install the native-image extension:

Finally, run the build the native-image-client-libraries-sample project with the `native-image` profile:

This build process may take a few minutes. Once the build finishes, you will have everything you need to see the performance differences in action!

The generated executable is in the "target" directory. Run the program to see it receives notifications from the Cloud Storage bucket

https://storage.googleapis.com/gweb-cloudblog-publish/images/Side-by-side.max-800x800.png

In this example, the native image started up 159x faster than the regular jar, and finished 19 times faster as well. The results of native image compilation can vary greatly depending on the workload, so feel free to experiment with your own applications to get the most out of your cloud resources.

Conclusion

This is only one example of how native image compilation is supported in Cloud Java Client Libraries. Please check out our official documentation to learn more about what libraries are supported and how you can build applications as native images. The documentation page also links to a couple of samples that you can try out.

Posted in