Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI and machine learningbreadcrumb arrow Grafana AI Observabilitybreadcrumb arrow Get startedbreadcrumb arrow Instrument Java
Grafana Cloud

Instrument Java agents

This guide shows you how to install the AI Observability Java SDK, instrument an LLM call, and verify that generation data reaches AI Observability.

Note

AI Observability is referred to as “Sigil” in SDKs, package names, and configuration. For example, the Maven artifact is com.grafana.sigil:sigil-sdk.

Before you begin

  • A running AI Observability instance or Grafana Cloud stack with AI Observability enabled.
  • Java 17 or later.
  • Your AI Observability generation export endpoint URL.

Install the SDK

Add the AI Observability SDK dependency to your project. For Maven:

xml 
<dependency>
    <groupId>com.grafana.sigil</groupId>
    <artifactId>sigil-sdk</artifactId>
</dependency>

Provider helpers and framework integrations are available as separate artifacts.

Capture a generation

java 
SigilClient client = new SigilClient(new SigilClientConfig()
    .setGenerationExport(new GenerationExportConfig()
        .setProtocol(GenerationExportProtocol.HTTP)
        .setEndpoint("<SIGIL_ENDPOINT>/api/v1/generations:export")
        .setAuth(new AuthConfig()
            .setMode(AuthMode.TENANT)
            .setTenantId("<TENANT_ID>"))));

try {
    client.withGeneration(
        new GenerationStart()
            .setConversationId("conv-1")
            .setModel(new ModelRef()
                .setProvider("openai")
                .setName("gpt-4o")),
        recorder -> {
            recorder.setResult(new GenerationResult()
                .setOutput(List.of(
                    new Message()
                        .setRole(MessageRole.ASSISTANT)
                        .setParts(List.of(MessagePart.text("Hello from Sigil"))))));
            return null;
        }
    );
} finally {
    client.shutdown();
}

Replace SIGIL_ENDPOINT and TENANT_ID with your values.

Use a provider helper

Provider helpers are available for OpenAI, Anthropic, and Gemini. They capture generations automatically from your LLM client calls.

Use a framework integration

A Google ADK framework integration is available for Java.

Configure authentication

For Grafana Cloud, use basic auth:

java 
new AuthConfig()
    .setMode(AuthMode.BASIC)
    .setTenantId("<INSTANCE_ID>")
    .setBasicPassword("<API_KEY>")

Verify data

Open the AI Observability plugin in Grafana and navigate to Conversations. Your generation should appear within a few seconds.

Next steps