GraalVM example for Kotlin AWS SDK (#1398)

Author: Kashif-E

examples/cloudwatch-logs-graalvm/README.md

@@ -0,0 +1,77 @@
+## CloudWatch Logs Reader with GraalVM Native Image
+
+### Overview
+
+This project is a Kotlin-based application that reads log events from AWS CloudWatch Logs. It uses the AWS SDK for
+Kotlin and is configured to run as a native image using GraalVM. More information about GraalVM native images can be found in the [official documentation](https://www.graalvm.org/latest/reference-manual/native-image/).
+
+### How to Use
+
+#### Prerequisites
+
+<ul>
+<li> JDK 17</li>
+<li> GraalVM</li>
+<li> Gradle</li>
+<li> AWS credentials configured (e.g, using AWS CLI)</li>
+</ul>
+
+### What is GraalVM?
+
+GraalVM is a high-performance runtime that provides significant improvements in application performance and efficiency.
+It supports multiple languages and execution modes, including:
+
+- **JVM-based languages**: Java, Kotlin, Scala, etc.
+- **LLVM-based languages**: C, C++, Rust, etc.
+- **Dynamic languages**: JavaScript, Python, Ruby, etc.
+
+GraalVM can compile Kotlin applications into native executables, which improves startup time and reduces memory usage.
+
+### Running the Application with Configured Gradle Task
+
+The `nativeRun` Gradle task is configured to run the application as a native image. Here is a brief explanation of the
+configuration:
+
+- **Region**: The AWS region where your CloudWatch Logs are located.
+- **Log Group**: The name of the log group you want to read logs from.
+- **Log Stream**: The name of the log stream you want to read logs from.
+- **The task**: is defined in the `build.gradle.kts` file.
+
+This task uses the GraalVM native image plugin to build and run the application with the specified arguments.
+
+```kotlin
+tasks.named<org.graalvm.buildtools.gradle.tasks.NativeRunTask>("nativeRun") {
+    this.runtimeArgs = listOf("ap-southeast-1", "my-log-group", "my-log-stream")
+}
+```
+
+### Reflection Configuration for GraalVM
+
+GraalVM doesn’t support reflection automatically. If your code or any library you use relies on reflection, you’ll need to set it up manually when building native images. This is done by creating a reflection configuration file. The configuration file should be placed in the `src/main/resources/META-INF/native-image` directory.
+
+Here is an example of a reflection configuration file [src/main/resources/META-INF/native-image/reflect-config.json](src/main/resources/META-INF/native-image/aws/sdk/kotlin/example/reflect-config.json):
+
+```json
+[
+  {
+    "name": "com.example.YourClass",
+    "allDeclaredConstructors": true,
+    "allDeclaredMethods": true,
+    "allDeclaredFields": true
+  }
+]
+```
+
+In the `build.gradle.kts` file, ensure that the `META-INF/native-image` directory is added to the classpath for reflection configuration:
+```kotlin
+graalvmNative {
+    binaries.all {
+        resources.autodetect()
+        // Add the META-INF/native-image directory to the classpath for reflection configuration
+        configurationFileDirectories.from(file("src/main/resources/META-INF/native-image"))
+    }
+}
+```
+This configuration ensures that the necessary reflection metadata is available at runtime for the native image.
+For more details, you can refer to the [official GraalVM documentation on reflection configuration](https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/Reflection/).
+

examples/cloudwatch-logs-graalvm/build.gradle.kts

@@ -0,0 +1,40 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+plugins {
+    kotlin("jvm")
+    id("org.graalvm.buildtools.native") version "0.10.2"
+    application
+}
+
+application {
+    mainClass.set("aws.sdk.kotlin.example.MainKt")
+}
+
+val awsSdkKotlinVersion: String by project
+val kotlinxDatetimeVersion: String by project
+
+kotlin {
+    jvmToolchain {
+        this.languageVersion.set(JavaLanguageVersion.of(17))
+    }
+}
+
+dependencies {
+    implementation(kotlin("stdlib"))
+    implementation("aws.sdk.kotlin:cloudwatchlogs:$awsSdkKotlinVersion")
+    implementation("org.jetbrains.kotlinx:kotlinx-datetime:$kotlinxDatetimeVersion")
+}
+
+graalvmNative {
+    binaries.all {
+        resources.autodetect()
+        // Add the META-INF/native-image directory to the classpath for reflection configuration
+        configurationFileDirectories.from(file("src/main/resources/META-INF/native-image"))
+    }
+}
+
+tasks.named<org.graalvm.buildtools.gradle.tasks.NativeRunTask>("nativeRun") {
+    this.runtimeArgs = listOf("ap-southeast-1", "my-log-group", "my-log-stream")
+}

examples/cloudwatch-logs-graalvm/src/main/kotlin/Main.kt

@@ -0,0 +1,65 @@
+package aws.sdk.kotlin.example
+
+import aws.sdk.kotlin.services.cloudwatchlogs.CloudWatchLogsClient
+import aws.sdk.kotlin.services.cloudwatchlogs.model.GetLogEventsRequest
+import aws.sdk.kotlin.services.cloudwatchlogs.paginators.getLogEventsPaginated
+import kotlinx.coroutines.flow.buffer
+import kotlinx.coroutines.runBlocking
+import kotlinx.datetime.Instant
+import kotlinx.datetime.TimeZone
+import kotlinx.datetime.toLocalDateTime
+
+/**
+ * This program reads log events from a specified AWS CloudWatch Logs stream.
+ *
+ * Usage:
+ * The program expects three command-line arguments:
+ * 1. `region` - The AWS region where the CloudWatch Logs are located.
+ * 2. `logGroupName` - The name of the CloudWatch Logs group.
+ * 3. `logStreamName` - The name of the CloudWatch Logs stream.
+ *
+ * The program performs the following steps:
+ * 1. Validates the input arguments.
+ * 2. Creates a `CloudWatchLogsClient` for the specified region.
+ * 3. Uses the `CloudWatchLogsReader` to fetch and print log events from the specified log stream.
+ * 4. Handles any exceptions that occur during the process and prints error messages.
+ * 5. Closes the `CloudWatchLogsClient` after processing.
+ *
+ * Example:
+ * tasks.named<org.graalvm.buildtools.gradle.tasks.NativeRunTask>("nativeRun") {
+ * this.runtimeArgs = listOf("us-southeast-1", "my-log-group", "my-log-stream")
+ * }
+ *
+ * Ensure that the AWS credentials and necessary permissions are configured properly for accessing CloudWatch Logs. */
+
+fun main(args: Array<String>) = runBlocking {
+    val usage = """
+        Usage: Required <region> <logGroupName> <logStreamName>
+    """.trimIndent()
+    if (args.size != 3) {
+        throw IllegalArgumentException(usage)
+    }
+
+    val region = args[0]
+    val logGroupName = args[1]
+    val logStreamName = args[2]
+
+    val request = GetLogEventsRequest {
+        this.logGroupName = logGroupName
+        this.logStreamName = logStreamName
+    }
+
+    CloudWatchLogsClient { this.region = region }.use { client ->
+        client.getLogEventsPaginated(request).buffer(4).collect { response ->
+            response.events?.forEach { logEvent ->
+                println("Log Event: ${logEvent.message} ${logEvent.timestamp?.formattedDateTime()}")
+            }
+        }
+    }
+}
+
+fun Long.formattedDateTime(): String {
+    val timestamp = Instant.fromEpochMilliseconds(this)
+    val dateTime = timestamp.toLocalDateTime(TimeZone.UTC)
+    return "${dateTime.dayOfMonth}-${dateTime.monthNumber}-${dateTime.year} ${dateTime.hour}:${dateTime.minute}:${dateTime.second}"
+}

examples/cloudwatch-logs-graalvm/src/main/resources/META-INF/native-image/aws/sdk/kotlin/example/reflect-config.json

@@ -0,0 +1,9 @@
+[
+  {
+    "name": "aws.sdk.kotlin.services.cloudwatchlogs.CloudWatchLogsClient",
+    "allDeclaredConstructors": true,
+    "allPublicConstructors": true,
+    "allDeclaredMethods": true,
+    "allPublicMethods": true
+  }
+]

examples/gradle.properties

@@ -1,3 +1,6 @@
 
 # AWS SDK
 awsSdkKotlinVersion=1.+
+
+# Kotlin DateTime library
+kotlinxDatetimeVersion=0.6.1

examples/gradle/wrapper/gradle-wrapper.jar

@@ -1,5 +1,7 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.8.3-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists