ka2a documentation
Output formats
Developer preview. Not yet production ready. This page is rendered from docs/output-formats.md of the ka2a repository at revision 96fb45e5e5f6693e779837998c3aa9581d6a37f2. It describes the behavior of that revision.
Contents
With --output json, each ka2a command prints one JSON document on stdout. pkg/observe
writes the snapshot documents. Each document has a member format that names its format and
its version, for example ka2a.doctor/1. Use this member to select a parser.
Tests keep this reference complete:
TestOutputFormatsReferenceListsEveryFormat(internal/cli) fails when the source names a format identifier that this reference does not name, or when a document of the command line or ofpkg/observehas no row in the table below.TestVersionedDocumentsOnlyGainMembers(internal/cli) holds the JSON members of each document ininternal/cli/testdata/output-members.golden, with their JSON kind. It enforces the compatibility rule below.
Compatibility rule
The rule is a product guarantee (KA2A-R1-017, scenario "Versioned output document").
- A document of one version (
/1) only gains members in a later ka2a revision. A new member can be absent ornullin an older document. - ka2a never removes, renames or retypes a member of a published version, and never changes
the meaning of a member or of one of its fixed values. Such a change makes the next version
(for example
ka2a.snapshot/2), with a new identifier. - A set of fixed values (for example
outcome,resultor a check status) can gain values. An error reference token keeps its meaning. - A consumer ignores members that it does not know, and treats an unknown value of a fixed
set as "needs attention". A consumer refuses a document whose
formatit does not know. - The text output (without
--output json) has no compatibility guarantee. Scripts use the JSON output and the exit codes.
observe.Decode (and ka2a serve-ui --snapshot FILE) reads ka2a.snapshot/1 strictly: it
refuses unknown members, so that a damaged or foreign file cannot pass as a snapshot. Read a
snapshot file with the ka2a revision that wrote it, or with a newer one. An older revision can
refuse the file of a newer revision with invalid_snapshot.
The members of a version are in the golden list. A new version gets its own lines, and the lines of the earlier version stay as long as ka2a writes it.
Product documents
| Format | Written by | Go type | Content |
|---|---|---|---|
ka2a.version/1 | ka2a version | versionResult (internal/cli/version.go) | Version, commit, Go version, platform, wire profile, store schema version and snapshot format. |
ka2a.doctor/1 | ka2a doctor | doctorResult (internal/cli/doctor.go) | The state directory, the check time, the result (ok or problems), the counts of problems, warnings and unverified settings, and each check with its name, status and detail. |
ka2a.snapshot/1 | ka2a observe, the file of ka2a snapshot export | observe.Snapshot (pkg/observe/snapshot.go) | A bounded, read-only view of one store: source and freshness, identifier mode, node, quarantine, storage, configuration, broker, counts, outbox, operations, dispatch, rejections, partitions and incidents. Lists are pages with a cursor. |
ka2a.snapshot.export/1 | ka2a snapshot export --out FILE | exportResult (internal/cli/observe.go) | The path and size of the written file, its snapshot format, capture time, identifier mode and whether an owner held the store lock. |
ka2a.operation/1 | ka2a operation show | observe.OperationView (pkg/observe/snapshot.go) | One operation with its source, identifier mode, node and the four acceptance stages. |
ka2a.topics.verify/1 | ka2a topics verify | topicResult (internal/cli/topics.go) | The topic, the profile, the result (see topic check results) and each check. |
ka2a.topics.provision/1 | ka2a topics provision | topicResult (internal/cli/topics.go) | As ka2a.topics.verify/1, and whether the command created the topic. |
ka2a.topics.acl-plan/1 | ka2a topics acl-plan | aclPlan (internal/cli/aclplan.go) | The principal, endpoint, mailbox topic, consumer group, the minimal ACLs, the matching kafka-acls.sh commands and notes. |
ka2a.serve-ui/1 | ka2a serve-ui (one line when it listens) | uiReady (internal/cli/serveui.go) | The UI address, the token file and the source. Never the token. |
ka2a.init/1 | ka2a init | initResult (internal/cli/init.go) | The state directory, the node identity, the catalog digest, the signing key and whether the store was created. |
ka2a.backup/1 | ka2a backup | backupResult (internal/cli/store.go) | Backup ID, path, time, schema version, SHA-256, size, source node, live epoch and coverage. |
ka2a.restore/1 | ka2a restore | restoreResult (internal/cli/store.go) | Backup ID, source, restore time, the path of the previous database and the next step. |
ka2a.quarantine.release/1 | ka2a quarantine release | releaseResult (internal/cli/store.go) | The released reason, the quarantine start, the operator, the previous generation, the node, the held rows and the next step. |
ka2a.held.release/1 | ka2a held release | heldResult (internal/cli/held.go) | The decided row: kind, operation, previous and new state and reason, attempts and the next step. |
ka2a.held.abandon/1 | ka2a held abandon | heldResult (internal/cli/held.go) | As ka2a.held.release/1, for an abandoned row or operation. |
ka2a.run/1 | ka2a run (one line when the node is ready) | runReady (internal/cli/run.go) | Endpoint, mailbox topic, profile, handler, and the UI, token file and metrics addresses. |
ka2a.send/1 | ka2a send | requestResult (internal/cli/request.go) | Operation, peer, operation ID, whether the operation is new, the outcome, the stages, the task or message, an A2A error, the result (only with --show-result), the identifier mode and a note. |
ka2a.task.get/1 | ka2a task get | requestResult (internal/cli/request.go) | As ka2a.send/1. |
ka2a.tasks.list/1 | ka2a tasks list | requestResult (internal/cli/request.go) | As ka2a.send/1, with a page of tasks. |
ka2a.task.cancel/1 | ka2a task cancel | requestResult (internal/cli/request.go) | As ka2a.send/1. |
ka2a.keys.generate/1 | ka2a keys generate | keyResult (internal/cli/keys.go) | The key file and the catalog key entry. Never the private key. |
ka2a.keys.public/1 | ka2a keys public | keyResult (internal/cli/keys.go) | As ka2a.keys.generate/1, for an existing key. |
ka2a.catalog.validate/1 | ka2a catalog validate | catalogValidateResult (internal/cli/catalog.go) | Path, digest, counts of endpoints, keys and grants, whether a node can load the catalog, and the findings with their class. |
ka2a.catalog.digest/1 | ka2a catalog digest | catalogDigestResult (internal/cli/catalog.go) | Path, SHA-256 digest of the exact bytes and the endpoints. |
ka2a.error/1 | every command that fails with --output json | errorDocument (internal/cli/cli.go) | The command, the error code, the message and the exit code. |
Development and qualification documents
The tests, examples and release tools of the repository write these documents. They are not part of the product interface. They follow the same rule while a report uses them, but a change to them needs no new product version.
| Format | Written by |
|---|---|
ka2a.example.embedded/1 | The summary line of examples/embedded. |
ka2a.example.recovery/1 | The result of examples/recovery. |
ka2a.qualification.embedded/1 | TestEmbeddedConsumerQualification (internal/qualification). |
ka2a.qualification.recovery/1 | The recovery walkthrough test (internal/qualification). |
ka2a.campaign-manifest/1 | The manifest of the KH campaign (internal/qualification/campaign). |
ka2a.campaign/1 | The summary of the KH campaign (internal/qualification/campaign). |
ka2a.protected-evaluator/1 | The pins of the protected evaluator (internal/qualification/evaluator). |
ka2a.evaluator-attempt/1 | One attempt of the protected evaluator (internal/qualification/evaluator). |
ka2a.model-results/1 | The Quint model summary (verification/scripts/pilot.mjs), read by the release evidence (internal/release). |
ka2a.model-bridge-traces/1 | The model-to-Go trace corpus (internal/modelbridge). |
ka2a.rapid-regression/1 | The Rapid regression corpus (internal/archtest). |
ka2a.load-report/1 | The load runs (benchmarks). |
ka2a.fresh-environment/1 | make fresh-environment (scripts/fresh_environment.py). |
ka2a.micro-benchmarks/1 | An earlier micro-benchmark report under reports/. No current tool writes it. |
File formats
These files are inputs or state, not command output. Their format names use the form .v1.
| Format | File |
|---|---|
ka2a.catalog.v1 | The trusted catalog. See Catalog format. |
ka2a.signing-key.v1 | A signing key file of ka2a keys generate. |
ka2a.store-epoch.v1 | The epoch witness store.epoch of a state directory. |
ka2a.recovery-marker.v1 | The recovery marker of a restored state directory. |