Diinstal secara manual, agen ARMS memantau kinerja aplikasi Java dan metrik bisnis AI, serta memerlukan konfigurasi variabel lingkungan dan pengaktifan tracing untuk pelaporan data. - Agent Run

Setelah diinstal, agen ARMS untuk aplikasi Java memungkinkan Anda melihat data pemantauan seperti topologi aplikasi, jejak (traces), pengecualian (exceptions), transaksi lambat, dan analisis SQL. Untuk aplikasi LLM seperti Agen, agen ini juga mengumpulkan metrik khusus AI, termasuk jumlah panggilan LLM, penggunaan token, jumlah jejak, dan jumlah sesi. Topik ini menjelaskan cara menginstal agen secara manual untuk aplikasi Java.

Prasyarat

Kebutuhan jaringan: Lingkungan build harus memiliki akses ke internet publik atau jaringan internal Alibaba Cloud, serta memerlukan akses TCP keluar pada port 80, 443, 8080, 8848, 9092, 9093, dan 9990.
Versi JDK: JDK 1.8, 11, 17, dan 21 didukung.
Kebutuhan memori: Ukuran heap maksimum JVM harus lebih dari 256 MB.

Penting

Fitur pemantauan LLM memerlukan agen ARMS versi 4.6.0 atau lebih baru. Versi Long-Term Support (LTS) saat ini, seperti 4.4.2, tidak mendukung fitur ini. Anda harus mengunduh versi agen yang ditentukan secara manual.

Prosedur

1. Unduh dan ekstrak agen

Unduh AliyunJavaAgent.zip (versi 4.6.0 atau lebih baru) dari halaman unduhan agen Konsol ARMS dan letakkan di direktori root proyek Anda.

Dalam Dockerfile Anda, ekstrak agen selama tahap run:

COPY AliyunJavaAgent.zip /tmp/AliyunJavaAgent.zip
RUN apk add --no-cache unzip && \
    unzip /tmp/AliyunJavaAgent.zip -d /opt/ && \
    rm -f /tmp/AliyunJavaAgent.zip

2. Konfigurasikan variabel lingkungan ARMS

Agen ARMS memerlukan tiga variabel lingkungan berikut agar dapat berjalan:

ARMS_APP_NAME: Nama aplikasi Anda, sebagaimana ditampilkan di Konsol ARMS.
ARMS_LICENSE_KEY: Kunci lisensi untuk aplikasi Anda. Anda dapat memperoleh kunci ini dengan memanggil operasi ListLicenseKey.
ARMS_REGION_ID: Wilayah tempat data observabilitas dilaporkan.

Untuk menggunakan Dockerfile yang sama untuk berbagai aplikasi, Anda dapat mengonfigurasi variabel lingkungan di konsol AgentRun saat menerapkan Agen, alih-alih melakukan hardcoding di Dockerfile.

3. Aktifkan agen

Muat agen Java dengan mengatur variabel lingkungan JAVA_TOOL_OPTIONS:

ENV JAVA_TOOL_OPTIONS="-javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar"

4. Mulai aplikasi

Teruskan konfigurasi menggunakan properti sistem dalam perintah startup Anda:

ENTRYPOINT ["sh", "-c", "java -Darms.licenseKey=${ARMS_LICENSE_KEY} -Darms.appName=${ARMS_APP_NAME} -Daliyun.javaagent.profileId=${ARMS_REGION_ID} -jar app.jar"]

Catatan

Jika ARMS_LICENSE_KEY kosong, agen dinonaktifkan secara diam-diam dan tidak memengaruhi operasi normal aplikasi Anda.

Contoh Dockerfile lengkap

Dockerfile

# Dockerfile multi-tahap untuk OpenAI Demo Java dengan Agen ARMS
# Mendukung pemantauan aplikasi Alibaba Cloud ARMS

# Tahap 1: Build aplikasi
FROM maven:3.9-eclipse-temurin-17 AS builder

WORKDIR /build

# Salin pom.xml dan unduh dependensi
COPY pom.xml .
RUN mvn dependency:go-offline -B

# Salin kode sumber dan build
COPY src ./src
RUN mvn clean package -DskipTests -B

# Tahap 2: Jalankan aplikasi dan instal agen ARMS
FROM eclipse-temurin:17-jre-alpine

WORKDIR /app

# ╔═══════════════════════════════════════════════════════════════════════════╗
# ║             Konfigurasi Agen ARMS - Langkah 1: Salin paket agen            ║
# ╠═══════════════════════════════════════════════════════════════════════════╣
# ║ Salin paket Agen Java ARMS yang telah diunduh sebelumnya ke dalam image.   ║
# ║ Paket agen perlu diunduh secara manual dan ditempatkan di direktori root proyek. ║
# ║ URL unduh: https://arms.console.alibabacloud.com/#/tracing/agentList/ap-southeast-1?tab=java   ║
# ╚═══════════════════════════════════════════════════════════════════════════╝
COPY AliyunJavaAgent.zip /tmp/AliyunJavaAgent.zip

# ╔═══════════════════════════════════════════════════════════════════════════╗
# ║             Konfigurasi Agen ARMS - Langkah 2: Ekstrak agen                ║
# ╠═══════════════════════════════════════════════════════════════════════════╣
# ║ Ekstrak paket agen ke direktori /opt/AliyunJavaAgent/.                    ║
# ║ Setelah diekstrak, berisi aliyun-java-agent.jar dan file lainnya.         ║
# ║ Bersihkan file zip sementara untuk mengurangi ukuran image.               ║
# ╚═══════════════════════════════════════════════════════════════════════════╝
RUN unzip /tmp/AliyunJavaAgent.zip -d /opt/ && \
    rm -f /tmp/AliyunJavaAgent.zip

# Salin artefak build
COPY --from=builder /build/target/OpenAI-Demo-Java-*.jar app.jar

# Ekspos port
EXPOSE 8080

# ╔═══════════════════════════════════════════════════════════════════════════╗
# ║         Konfigurasi Agen ARMS - Langkah 3: Konfigurasi variabel lingkungan ARMS ║
# ╠═══════════════════════════════════════════════════════════════════════════╣
# ║ ARMS_LICENSE_KEY: Kunci lisensi ARMS, digunakan untuk otentikasi aplikasi dan pelaporan data. ║
# ║ ARMS_APP_NAME: Nama aplikasi, pengenal yang ditampilkan di Konsol ARMS.   ║
# ║ ARMS_REGION_ID: Wilayah tempat data observabilitas dilaporkan.            ║
# ╚═══════════════════════════════════════════════════════════════════════════╝
ENV ARMS_LICENSE_KEY="hc4fs1*****@d2fb***********"
ENV ARMS_APP_NAME="OpenAI-Demo-Java-1112"
ENV ARMS_REGION_ID={RegionId}

# ╔═══════════════════════════════════════════════════════════════════════════╗
# ║  Konfigurasi Agen ARMS - Langkah 4: Konfigurasi JAVA_TOOL_OPTIONS untuk mengaktifkan agen ARMS ║
# ╠═══════════════════════════════════════════════════════════════════════════╣
# ║ Variabel lingkungan JVM standar ini dibaca secara otomatis oleh JVM saat startup. ║
# ║ Muat agen ARMS menggunakan parameter -javaagent untuk mengaktifkan pemantauan kinerja aplikasi dan tracing. ║
# ║ Agen secara otomatis mengumpulkan metrik kinerja, jejak, pengecualian, dan data lainnya. ║
# ╚═══════════════════════════════════════════════════════════════════════════╝
ENV JAVA_TOOL_OPTIONS="-javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar"
# Periksa konfigurasi variabel lingkungan
RUN echo "JAVA_TOOL_OPTIONS: ${JAVA_TOOL_OPTIONS}"

# ╔═══════════════════════════════════════════════════════════════════════════╗
# ║             Konfigurasi Agen ARMS - Langkah 5: Mulai aplikasi             ║
# ╠═══════════════════════════════════════════════════════════════════════════╣
# ║ Teruskan konfigurasi ARMS ke agen melalui properti sistem -D.             ║
# ║ Agen secara otomatis menyisipkan diri ke dalam aplikasi untuk memantau status waktu proses dan metrik kinerjanya. ║
# ║ Jika ARMS_LICENSE_KEY kosong, agen dinonaktifkan tetapi tidak memengaruhi operasi normal aplikasi. ║
# ╚═══════════════════════════════════════════════════════════════════════════╝
ENTRYPOINT ["sh", "-c", "java -Darms.licenseKey=${ARMS_LICENSE_KEY} -Darms.appName=${ARMS_APP_NAME} -Daliyun.javaagent.profileId=${ARMS_REGION_ID} -jar app.jar"]

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.7</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>
  <groupId>com.example</groupId>
  <artifactId>OpenAI-Demo-Java</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>OpenAI-Demo-Java</name>
  <description>Demo project for Spring Boot</description>
  <url/>
  <licenses>
    <license/>
  </licenses>
  <developers>
    <developer/>
  </developers>
  <scm>
    <connection/>
    <developerConnection/>
    <tag/>
    <url/>
  </scm>
  <properties>
    <java.version>17</java.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>

    <!-- OpenAI Java SDK -->
    <!-- <dependency>
    <groupId>com.openai</groupId>
    <artifactId>openai-java</artifactId>
    <version>2.6.0</version>
  </dependency> -->
    <dependency>
      <groupId>com.openai</groupId>
      <artifactId>openai-java-spring-boot-starter</artifactId>
      <version>4.7.1</version>
    </dependency>
  </dependencies>

  <build>
    <finalName>OpenAI-Demo-Java</finalName>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>

</project>

OpenAiDemoJavaApplication.java

package com.example.OpenAI_Demo_Java;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Demo OpenAI - Contoh pemanggilan Alibaba Cloud Qwen
 * 
 * Penggunaan:
 * 1. Konfigurasikan dashscope.api.key di application.properties
 * 2. Jalankan aplikasi: ./mvnw spring-boot:run
 * 3. Akses titik akhir: curl http://localhost:8080/
 */
@SpringBootApplication
@RestController
public class OpenAiDemoJavaApplication {

    @Value("${dashscope.api.key:sk-ed8d03d6e7*****************}")
    private String apiKey;

    private OpenAIClient client;

    public static void main(String[] args) {
        SpringApplication.run(OpenAiDemoJavaApplication.class, args);
    }

    /**
	 * Inisialisasi klien OpenAI
	 */
    @Bean
    public OpenAIClient openAIClient() {
        // Prioritaskan Kunci API dari file konfigurasi. Jika tidak ada, gunakan variabel lingkungan.
        String key = apiKey.isEmpty() ? System.getenv("DASHSCOPE_API_KEY") : apiKey;

        if (key == null || key.isEmpty()) {
            throw new IllegalStateException("API Key not configured! Please set dashscope.api.key in application.properties");
        }

        client = OpenAIOkHttpClient.builder()
        .apiKey(key)
        .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
        .build();

        return client;
    }

    /**
	 * Titik akhir HTTP: GET /
	 * Mengirimkan prompt ke model bahasa besar dan mengembalikan tanggapan.
	 */
    @GetMapping("/")
    public String chat() {
        try {
            // Buat parameter permintaan
            ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
            .addUserMessage("Write a haiku about a forest")
            .model("qwen-plus")
            .build();

            // Panggil API
            ChatCompletion response = client.chat().completions().create(params);

            // Ekstrak konten tanggapan
            String content = response.choices().get(0).message().content().orElse("No response");

            return String.format("Prompt: Write a haiku about a forest\n\nAnswer: %s", content);

        } catch (Exception e) {
            return "Error: " + e.getMessage();
        }
    }
}

package com.example.OpenAI_Demo_Java;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * OpenAI Demo - Contoh pemanggilan Alibaba Cloud Qwen
 * 
 * Penggunaan:
 * 1. Konfigurasikan dashscope.api.key di application.properties
 * 2. Jalankan aplikasi: ./mvnw spring-boot:run
 * 3. Akses titik akhir: curl http://localhost:8080/
 */
@SpringBootApplication
@RestController
public class OpenAiDemoJavaApplication {

    @Value("${dashscope.api.key:sk-ed8d03d6e7*****************}")
    private String apiKey;

    private OpenAIClient client;

    public static void main(String[] args) {
        SpringApplication.run(OpenAiDemoJavaApplication.class, args);
    }

    /**
	 * Inisialisasi klien OpenAI
	 */
    @Bean
    public OpenAIClient openAIClient() {
        // Utamakan API Key dari file konfigurasi. Jika tidak ada, gunakan variabel lingkungan.
        String key = apiKey.isEmpty() ? System.getenv("DASHSCOPE_API_KEY") : apiKey;

        if (key == null || key.isEmpty()) {
            throw new IllegalStateException("API Key belum dikonfigurasi! Harap atur dashscope.api.key di application.properties");
        }

        client = OpenAIOkHttpClient.builder()
        .apiKey(key)
        .baseUrl("https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
        .build();

        return client;
    }

    /**
	 * Titik akhir HTTP: GET /
	 * Mengirim prompt ke model bahasa besar dan mengembalikan respons.
	 */
    @GetMapping("/")
    public String chat() {
        try {
            // Bangun parameter permintaan
            ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
            .addUserMessage("Write a haiku about a forest")
            .model("qwen-plus")
            .build();

            // Panggil API
            ChatCompletion response = client.chat().completions().create(params);

            // Ekstrak konten respons
            String content = response.choices().get(0).message().content().orElse("No response");

            return String.format("Prompt: Write a haiku about a forest\n\nAnswer: %s", content);

        } catch (Exception e) {
            return "Error: " + e.getMessage();
        }
    }
}

Terapkan dan verifikasi

Build dan dorong image

Build Dockerfile menjadi image dan dorong ke Container Registry atau repositori image lain yang dapat diakses.

# Contoh: Dorong citra ke Alibaba Cloud ACR
# 1. Beri tag pada citra
docker tag {LOCAL_IMAGE_TAG} registry.ap-southeast-1.aliyuncs.com/{YOUR_ACR_NAMESPACE}/{YOUR_ACR_REPOSITORY_NAME}:{IMAGE_VERSION}

# 2. Dorong citra
docker push registry.ap-southeast-1.aliyuncs.com/{YOUR_ACR_NAMESPACE}/{YOUR_ACR_REPOSITORY_NAME}:{IMAGE_VERSION}

# Contoh: Dorong image ke Alibaba Cloud ACR
# 1. Beri tag image
docker tag {LOCAL_IMAGE_TAG} registry.ap-southeast-1.aliyuncs.com/{YOUR_ACR_NAMESPACE}/{YOUR_ACR_REPOSITORY_NAME}:{IMAGE_VERSION}

# 2. Dorong image
docker push registry.ap-southeast-1.aliyuncs.com/{YOUR_ACR_NAMESPACE}/{YOUR_ACR_REPOSITORY_NAME}:{IMAGE_VERSION}

Terapkan dan konfigurasikan agen di AgentRun

Masuk ke Konsol AgentRun. Di tab Agent Runtime, klik Create agent.
Pilih Create with code, lalu masukkan Agent name dan Description.
Di bagian Code configuration, konfigurasikan parameter berikut:
- Code source: Pilih Container Image.
- Container registry instance, Container Registry Repository: Pilih image yang telah Anda dorong.
Startup Command: Jika Anda telah mengonfigurasi ini dengan CMD di Dockerfile Anda, Anda dapat mengosongkannya.
Listening port: Masukkan port tempat aplikasi Anda mendengarkan, misalnya 8000.
Resource configuration: Alokasikan CPU dan memori untuk agen sesuai kebutuhan.
Konfigurasi variabel lingkungan agen (Direkomendasikan): Rujuk ke Langkah 2 untuk mengonfigurasi variabel lingkungan ARMS_APP_NAME, ARMS_LICENSE_KEY, dan ARMS_REGION_ID.
Enable tracing: Di pengaturan lanjutan, aktifkan sakelar Enable tracing.

Peringatan
Jika sakelar Enable tracing dimatikan, semua konfigurasi agen tidak berlaku, dan aplikasi tidak dapat melaporkan data pemantauan.
Klik Start deployment.

Verifikasi status agen

Setelah penerapan berhasil, tunggu 1 hingga 2 menit. Buka halaman Details agen, lalu halaman Observability untuk memeriksa hal berikut:

Di tab Overview, periksa apakah jumlah permintaan, jumlah panggilan LLM, dan penggunaan token ditampilkan.
Di Trace List, verifikasi bahwa jejak untuk panggilan openai atau dashscope muncul.

Agent Run:Instal agen ARMS untuk aplikasi Java