Java SDK

Das Java-SDK (sdk/java, Paket ledgersdk) deckt die manuelle record-API ab. Es benötigt JDK 17+ und hat keine externen Abhängigkeiten (java.net.http plus ein minimaler eingebauter JSON-Writer). OTel-instrumentierte Java-Apps — einschließlich des Zero-Code-Java-Agents — sollten stattdessen ihren bestehenden Exporter auf den OTLP-Receiver des Ledgers richten (/v1/otlp/v1/traces); hier gibt es keinen Span-Prozessor.

Installation

Noch nicht auf Maven veröffentlicht. Binden Sie sdk/java/src vorerst als Vendor-Verzeichnis in Ihr Projekt ein:

javac -d out sdk/java/src/*.java

Schnellstart

import ledgersdk.LedgerClient;
import java.time.Instant;
import java.util.List;
import java.util.Map;

LedgerClient ledger = new LedgerClient(
    "http://127.0.0.1:4010", ingestKey, "urn:agent:research-assistant"
);
ledger.setTrigger("human", "person@example.com");

Instant started = Instant.now().minusSeconds(1);
Instant ended = Instant.now();

String spanId = ledger.record(Map.of(
    "action_type", "llm_call",
    "provider", "anthropic",
    "model", "claude-fable-5",
    "started_at", started,
    "ended_at", ended,
    "status", "success",
    "usage", Map.of("tokens_in", 420, "tokens_out", 180),
    "payloads", List.of(Map.of("kind", "response", "content", "The policy provides that…"))
));

ledger.flush();

record() nimmt eine Map<String, Object> entgegen, deren Keys direkt den Wire-Vertrag widerspiegeln (snake_case, dieselben Feldnamen wie bei jedem anderen SDK). Es wirft nie eine Exception in die Host-Anwendung — Fehler gehen stattdessen an ledger.onError.

Entscheidungs-Lineage

Nehmen Sie parent_ref in die Map auf, um auf die Span zu verweisen, die dieses Event verursacht hat — lassen Sie es weg, um auf die jeweils geltende ambiente/Standard-Zuordnung zurückzufallen.

Flushen

flush() liefert gepufferte Events aus und kann gefahrlos per Timer oder vor dem Herunterfahren aufgerufen werden. Die Zustellung erfolgt at-least-once — der Server dedupliziert nach Span-ID.