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

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.

Resources

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

License

This project is licensed under the Apache License 2.0