SDK de Java

El SDK de Java (sdk/java, paquete ledgersdk) cubre la API manual record. Necesita JDK 17+ y no tiene dependencias externas (java.net.http más un escritor JSON mínimo incorporado). Las aplicaciones de Java instrumentadas con OTel — incluido el agente Java sin cambios de código — deberían apuntar su exportador ya existente al receptor OTLP del ledger (/v1/otlp/v1/traces) en su lugar; aquí no hay procesador de spans.

Instalación

Aún no está publicado en Maven. Por ahora, incorpore sdk/java/src a su proyecto:

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

Inicio rápido

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() toma un Map<String, Object> cuyas claves reflejan directamente el contrato de wire (snake_case, los mismos nombres de campo que cualquier otro SDK). Nunca lanza una excepción dentro de la aplicación anfitriona — los fallos van a ledger.onError en su lugar.

Linaje de decisiones

Incluya parent_ref en el map para citar el span que causó este evento — omítalo para recurrir a la atribución ambiental/por defecto que corresponda.

Flush

flush() entrega los eventos en buffer y es seguro llamarlo con un temporizador o antes del apagado. La entrega es al-menos-una-vez — el servidor deduplica por id de span.