SDK Java

Le SDK Java (sdk/java, package ledgersdk) couvre l'API manuelle record. Il nécessite JDK 17+ et n'a aucune dépendance externe (java.net.http plus un rédacteur JSON intégré minimal). Les applications Java instrumentées avec OTel — y compris l'agent Java sans code — devraient plutôt faire pointer leur exportateur existant vers le récepteur OTLP du registre (/v1/otlp/v1/traces) ; il n'y a pas de processeur de spans ici.

Installation

Pas encore publié sur Maven. Pour l'instant, intégrez sdk/java/src dans votre projet :

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

Démarrage rapide

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() prend une Map<String, Object> dont les clés reflètent directement le contrat de transmission (snake_case, mêmes noms de champs que tous les autres SDK). Elle ne lève jamais d'exception dans l'application hôte — les échecs sont dirigés vers ledger.onError à la place.

Lignée décisionnelle

Incluez parent_ref dans la map pour citer le span à l'origine de cet événement — omettez-le pour vous rabattre sur l'attribution ambiante/par défaut applicable.

Flush

flush() livre les événements en tampon et peut être appelé sans risque sur une minuterie ou avant l'arrêt. La livraison se fait au moins une fois (at-least-once) — le serveur déduplique par identifiant de span.