为自定义运行时Java Agent接入ARMS应用监控-函数计算-阿里云

AgentRun 自定义运行时 Agent 支持接入阿里云 ARMS 应用监控，支持为常见 AI 应用框架提供应用监控能力，接入 ARMS 探针后，可以了解 AI 应用的大模型调用次数、Token使用次数、Trace数、会话数等信息。本文介绍如何为自定义运行时 Java Agent 接入 ARMS 应用监控。

前提条件

已开通 ARMS 服务。具体操作请参见开通ARMS。
Java 版本选择自定义运行时中的Java 8、Java 11、Java 17和Java 21。

说明

与“自定义镜像部署”方案不同，本方案无需修改 Dockerfile 或构建镜像，所有配置均通过 AgentRun 控制台完成，更适合快速迭代和轻量级部署场景。

配置步骤

1、设置探针环境变量

在 Agent 运行时详情页面，选择概览与配置页签，单击编辑配置，添加以下环境变量：

ARMS_APP_NAME={AgentName}
ARMS_LICENSE_KEY={LicenseKey}

变量含义说明：

ARMS_APP_NAME：Agent 名字，用于在 ARMS 应用监控中显示
ARMS_LICENSE_KEY：ARMS 为您生成的应用接入凭证，可以通过 OpenAPI 获取，具体方法可参见DescribeTraceLicenseKey - 列出LicenseKey。

2、修改启动命令

方式一：使用JAVA_TOOL_OPTIONS环境变量

在环境变量中添加JAVA_TOOL_OPTIONS环境变量，这将作为启动命令的一部分在启动时拼接到命令中。

JAVA_TOOL_OPTIONS="\
-javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar \
-Darms.licenseKey=${ARMS_LICENSE_KEY} \
-Darms.appName=${ARMS_APP_NAME}"

方式二：配置启动脚本，使用数组来存储Java启动参数

使用ARMS需要添加3个启动参数，考虑到启动命令比较复杂，建议可以通过配置启动脚本bootstrap来启动。

示例代码如下所示：

#!/bin/bash
set -eo pipefail

# 1. 设置ARMS应用名称
# 如果ARMS_APP_NAME环境变量存在且不为空，则使用其值；否则使用默认值。
appName="${ARMS_APP_NAME:-Custom_Java_Arms_Demo}"
echo "appName: ${appName}"

# 使用数组来存储Java启动参数，这是处理参数的最佳实践
java_opts=()

# 2. 添加ARMS参数
if [[ -n "${ARMS_LICENSE_KEY}" ]]; then
    echo "ARMS_LICENSE_KEY is set: ${ARMS_LICENSE_KEY}, enabling ARMS agent."
    # 使用公共层的ARMS程序路径
    java_opts+=("-javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar")
    java_opts+=("-Darms.licenseKey=${ARMS_LICENSE_KEY}")
    java_opts+=("-Darms.appName=${appName}")
else
    echo "Warning: ARMS_LICENSE_KEY not set. ARMS agent will not be enabled."
fi

# 3. 启动应用程序
# 添加其他固定的Java参数
java_opts+=("-Dserver.port=8000")
echo "Final Java command: exec java ${java_opts[*]} -jar /code/target/OpenAI-Demo-Java.jar"

exec java "${java_opts[@]}" \
    -jar /code/target/OpenAI-Demo-Java.jar

设置文件权限为可执行权限（终端窗口执行命令chmod +x bootstrap）。

在 Agent 运行时详情页面，选择编辑配置，修改启动命令的值为启动脚本/bootstrap。

验证接入

保存配置更新Agent；
发起几次业务调用；
约 1 分钟后，前往以下任一位置查看数据：
- Agent运行时控制台 > Agent详情 > 可观测性
- ARMS 控制台 > 应用监控（或 LLM 应用监控） > 应用列表 > 您的应用名

若能看到调用链、Token 消耗、LLM 调用次数等数据，即表示接入成功。