The ledger is the list of the events your code emits, with their types, and what must hold between them. It lives in your repository, in logika.json, beside the code it describes; your agent writes it, you review it in pull requests, and Logika checks production against it every 5m. This page explains what's in it and how it works; the ledger reference has every key.
An empty ledger stores everything
A ledger can be empty, and every project's starts that way. Logika then stores everything your application sends, every span, log record and metric, and you and your agent can query all of it; and a span that fails, or a log record with an exception or an ERROR or FATAL severity, raises an issue, but nothing else alarms unless the ledger says so. That's step one: a logging platform, with no schema to write.
Each declaration from then on adds something. Declaring an event gives it a message you can read, types its values, and makes it something rules can talk about. Marking a param as an identity gives you distinct users and retention. You go as far as you like.
Params and events
A ledger has a vocabulary of params: each name declared once, with its type and its flags, and the same everywhere it's used.
"params": {
"order_id": {"type": "str"},
"user_id": {"type": "str", "identity": true},
"email": {"type": "str", "pii": true},
"amount": {"type": "decimal"},
"sku": {"type": "str"},
"provider": {"type": "str", "dimension": true},
"reason": {"type": "str", "dimension": true}
}
pii: encrypted on your machine, with a key only you hold, before it's sent; we can match it, never read it.identity: a person or an entity; Logika keeps one row per value per day, for exact counts and retention.dimension: few values, worth grouping by; Logika counts each one.
An event is something your code does, sent as an OpenTelemetry span of the same name: an operation with a beginning and an end, or a short span marking a moment. Each has a message template, the params it carries (a trailing ? makes one optional), and the children it's made of:
{"name": "checkout",
"message": "Checkout {order_id} for {user_id}: {amount}",
"params": ["order_id", "user_id", "email?", "amount"],
"span": {"timeout": "2m", "paths": ["reserved (captured|declined)"]},
"children": [
{"name": "reserved", "message": "Reserved {sku}", "params": ["sku"]},
{"name": "captured", "message": "Captured {amount} via {provider}", "params": ["amount", "provider"]},
{"name": "declined", "message": "Declined: {reason}", "params": ["reason"]}]}
The message is what you read wherever the event shows up: "Checkout ord_81 for usr_7: 49.00". A required param that stops arriving is an issue on its own; it catches "we stopped sending X", the bug nobody notices for a month.
Your code doesn't depend on any of this: it's plain OpenTelemetry, and the names and attribute keys simply match. logika check makes sure they do, without running anything.
Declaring makes history readable
Declaring something never loses what came before it. An attribute that arrived before its param was declared is kept with its span; once you declare it, queries read it as a typed column, and analytics fill in from it. So you can start with whatever your code sends today, and give it structure when you know what you want from it.
What the ledger judges
Beyond types, the ledger says what must hold: an event's values (validate, a SQL condition such as amount > 0), the order of an operation's steps (paths, regular expressions over its children's names), how long it may take (timeout), what one event obliges another to do and by when (rules), and relations between events across traces (invariants, SQL queries returning the rows that break them). Failures need no declaring: every span that fails, and every log record with an exception or an error severity, is an issue. These are written with you, from real captures, in reflection; and the ledger also carries the analytics you declare: funnels, milestones and views.
Checked continuously
Every 5m, the evaluator takes what arrived since its last pass and judges it against the ledger, with the rest of each trace as context. Each event is judged by the version of the ledger its code was built with: the enhancer sends the ledger's fingerprint with every batch, so old and new releases running side by side are each held to their own rules, and code built before a stricter rule is never judged by it.
What breaks the ledger becomes an issue, identified by what broke, not by the values involved: one issue per event however it failed, per rule, per invariant and key, per failing span (or logger) and exception type. Repeats are occurrences of the same issue, so a bad deploy is one email, not a thousand. Things that arrive late are judged when they arrive, and an issue that late data proves wrong (the span did finish in time; the expected event did come) is withdrawn, as long as no agent has started on it.
Versions and sync
logika sync sends the ledger to Logika. A ledger whose content changed is frozen as a new version, immutable, with its fingerprint; one that didn't change freezes nothing. Before it's accepted, it's validated against everything deployed before it: a param can't change its type once it has shipped, a rule can't reference an event that doesn't exist.
Nothing syncs on its own. You or your agent run it when you say the instrumentation is ready, or your release pipeline runs it. If code ships with a ledger that was never synced, its data is stored as usual but held from judgement, and the console says so until the ledger is synced; then the held data is judged by it.
Every deployed version is in the console, under Settings' Your ledger: what Logika watches, read-only, each event as one line with its params in place, any version a click away with what it changed from the one before.
Several branches can change the ledger at once; sync merges them the way git would, entry by entry (events by name, rules by what they relate), and stops on a real conflict, writing both sides into the file for you to settle. Several repositories can belong to one project, each with its own ledger, and a rule in one can expect an event of another.
The rest of logika.json
Beside the ledger, the same file holds the project it belongs to, the map of your repository's components (with each one's logging conventions, and whether it is instrumented yet), and the CLI's own config: the templates for typed bindings. The agent itself is set per environment in the console. None of it is part of the ledger's fingerprint, so editing it never makes the ledger look changed.