Java SDK

The Java SDK (sdk/java, package ledgersdk) covers the manual record API. It needs JDK 17+ and has zero external dependencies (java.net.http plus a minimal built-in JSON writer). OTel-instrumented Java apps — including the zero-code Java agent — should point their existing exporter at the ledger's OTLP receiver (/v1/otlp/v1/traces) instead; there's no span processor here.

Install

Not yet published to Maven. Vendor sdk/java/src into your project for now:

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

Quick start

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() takes a Map<String, Object> whose keys mirror the wire contract directly (snake_case, same field names as every other SDK). It never throws into the host application — failures go to ledger.onError instead.

Decision lineage

Include parent_ref in the map to cite the span that caused this event — omit it to fall back to whatever ambient/default attribution applies.

Flushing

flush() delivers buffered events and is safe to call on a timer or before shutdown. Delivery is at-least-once — the server dedups by span id.