LoongSuite Java GenAI Utils

English | 中文

简介

LoongSuite Java GenAI Utils 是阿里巴巴统一可观测数据采集套件 LoongSuite 的关键组件，为 Java GenAI instrumentation 提供共享的遥测生命周期管理能力。

LoongSuite 包含以下关键组件：

• LoongCollector：基于 eBPF 的通用节点 Agent。
• LoongSuite Java：Java GenAI 遥测工具库。
• LoongSuite Python：Python 应用进程级 Agent。
• LoongSuite Go：Golang 编译期 instrumentation Agent。
• LoongSuite JS：JavaScript AI Agent 的 OpenTelemetry 插件。

基于 OTel GenAI Semantic Conventions v1.41.1 实现，是 opentelemetry-util-genai 的 Java 对等实现。

Maven 坐标

将 ${otel-util-genai.version} 替换为 Maven Central 上 otel-util-genai 最新版本。

<dependency>
    <groupId>com.alibaba.loongsuite</groupId>
    <artifactId>otel-util-genai</artifactId>
    <version>${otel-util-genai.version}</version>
</dependency>

安装

将 ${otel-util-genai.version} 与 ${opentelemetry.version} 分别替换为 Maven Central 上 otel-util-genai 与 opentelemetry-bom 的最新发布版本。

Maven

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>${opentelemetry.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.alibaba.loongsuite</groupId>
        <artifactId>otel-util-genai</artifactId>
        <version>${otel-util-genai.version}</version>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
</dependencies>

Gradle

// 使用 Maven Central 上的最新版本
def otelUtilGenaiVersion = '...'      // otel-util-genai
def opentelemetryBomVersion = '...'   // opentelemetry-bom

implementation platform("io.opentelemetry:opentelemetry-bom:${opentelemetryBomVersion}")
implementation "com.alibaba.loongsuite:otel-util-genai:${otelUtilGenaiVersion}"
implementation 'io.opentelemetry:opentelemetry-sdk'
implementation 'io.opentelemetry:opentelemetry-exporter-otlp'

本库仅依赖 OTel API；未配置 SDK 与 Exporter 时不会产出遥测数据。

快速开始

OpenTelemetry openTelemetry =
    AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
GenAiTelemetryHandler handler = GenAiTelemetryHandler.create(openTelemetry);

try (InferenceInvocation inv = handler.inference("openai", "gpt-4o")) {
    inv.setInputMessages(
        Collections.singletonList(
            new InputMessage("user", Collections.singletonList(new TextPart("你好")))));
    // 调用你的 LLM 客户端后，记录响应：
    inv.setOutputMessages(
        Collections.singletonList(
            new OutputMessage(
                "assistant",
                Collections.singletonList(new TextPart("你好！")),
                "stop")));
}

完整用法（操作类型、流式、错误处理、环境变量、CompletionHook）见 docs/USAGE_zh.md。

文档

要求

• Java 8+
• OpenTelemetry API（使用最新的 opentelemetry-bom 发布版本）

社区

欢迎反馈与建议。可加入 钉钉用户群 与 钉钉开发者群。

用户群	开发者群

相关资源

• AgentScope：https://github.com/modelscope/agentscope
• 可观测性社区：https://observability.cn

License

This project is licensed under the Apache License 2.0