LoongSuite Java GenAI Utils

English | 中文

Introduction

LoongSuite Java GenAI Utils is a key component of LoongSuite, Alibaba's unified observability data collection suite, providing shared telemetry lifecycle management for Java GenAI instrumentation.

LoongSuite includes the following key components:

• LoongCollector: universal node agent for log, metric, and network collection based on eBPF.
• LoongSuite Java: GenAI telemetry utility library for Java.
• LoongSuite Python: process agent for Python applications.
• LoongSuite Go: compile-time instrumentation agent for Golang.
• LoongSuite JS: OpenTelemetry plugins for JavaScript AI agents.

Built on OTel GenAI Semantic Conventions v1.41.1, this library is the Java counterpart of opentelemetry-util-genai.

Maven Coordinates

Replace ${otel-util-genai.version} with the latest otel-util-genai release from Maven Central.

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

Installation

Replace ${otel-util-genai.version} and ${opentelemetry.version} with the latest releases of otel-util-genai and opentelemetry-bom from Maven Central.

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

// Use the latest releases from 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'

This library depends only on the OTel API. Without an SDK and exporter, operations are no-ops.

Quick Start

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

try (var inv = handler.inference("openai", "gpt-4o")) {
    inv.setInputMessages(List.of(new InputMessage("user", List.of(new TextPart("Hello")))));
    var response = client.chat(request);
    inv.setOutputMessages(List.of(
        new OutputMessage("assistant", List.of(new TextPart(response.content())), "stop")));
}

See docs/USAGE.md for all operation types, streaming, error handling, environment variables, and CompletionHook.

Documentation

Document	Description
docs/USAGE.md	Usage guide (operations, config, hooks)
examples/README.md	Spring Boot example (7 GenAI operations)

Requirements

• Java 17+
• OpenTelemetry API (use the latest opentelemetry-bom release)

Community

We are looking forward to your feedback and suggestions. You can join our DingTalk user group and DingTalk developer group to engage with us.

User Group	Developer Group

Resources

• AgentScope: https://github.com/modelscope/agentscope
• Observability Community: https://observability.cn

License

This project is licensed under the Apache License 2.0