Skip to content

Latest commit

 

History

History
89 lines (59 loc) · 9.88 KB

cli-contract.md

File metadata and controls

89 lines (59 loc) · 9.88 KB

JSON output and exit codes

This guide describes the output consumed by scripts and other tools. Output schemas are versioned separately from CLI releases and the capture file format. Online commands support the listed Collector releases.

Process and channels

  • Normal command output is UTF-8 JSON on stdout, terminated by a newline. xlog search and counter history emit JSONL: parse each nonempty line as one JSON object.
  • Command and argument errors also go to stdout as JSON. Do not assume stderr is the error API. Keep stdout and stderr separate when parsing.
  • Explicit interactive password input uses a terminal and a human-readable prompt on stderr. Automation should provide SCOUTERCTL_PASSWORD and use --no-input; it must not depend on prompt text.
  • --help and --version are plain-text stdout with exit 0, outside the JSON format. Help layout and diagnostic messages may change. Parse error codes rather than message text.
  • scouterctl COMMAND --help shows that command's required and accepted options, combinations and an example (for example scouterctl capture --help or scouterctl counter history --help). A command-family help request such as scouterctl counter --help lists its commands. Help contains no ANSI escapes when output is redirected or NO_COLOR is set, including an empty value.
  • These formats apply after the JVM and CLI start successfully. A missing/incompatible JVM, process termination or an unwritable output stream can prevent a valid JSON response. Missing or malformed output must not be treated as successful execution.

Single-result commands

collector status, collector config, agent status, agent config, counter list, counter get, counter export, doctor, auth login, object list, profile get, capture, context add/list/use, and the inspect family emit one result or one error object.

{"schemaVersion":"scouterctl.result/v1","ok":true,"data":{},"executionComplete":true}

data is command-specific: an array for object list, otherwise an object. An empty array or an empty context map is a valid successful result. Nested data.schemaVersion values describe that payload (for example contexts or captures); they do not replace the outer result schema.

ok: true means data was produced. It does not imply exit 0. A partial result retains its data, has executionComplete: false, and exits 8. For example, an explicitly truncated profile get produces this result shape rather than an error object. Capture completion means the requested export finished; a completed capture can store a truncated profile and exit 0, while inspecting that profile exits 8. Inspect the operation's scope and the profile's completeness separately.

Completion never certifies traffic coverage, sampling, comparability or profile completeness. unknown is not a positive assertion. A result-list limit may truncate the displayed rows without making the underlying capture incomplete; use the command's truncated and summary fields.

Errors and exit codes

{"schemaVersion":"scouterctl.error/v1","type":"error","ok":false,"error":{"code":"INVALID_ARGUMENT","message":"Invalid command arguments; use --help"}}

The example message is illustrative. error.code is the machine-readable identifier; error.message is a human-readable string. An error object contains no result data. During a stream, previously emitted records remain on stdout but are not a complete result.

Unknown options, invalid/missing option values and unsupported command-option combinations identify the offending option in error.message where available. Argument values are not echoed; error schema and exit codes are unchanged.

Exit Error code when an error object is emitted Meaning
0 None Requested command completed; scope limitations still apply
2 INVALID_ARGUMENT Invalid arguments, configuration or resume conditions
3 AUTH_FAILED Authentication or session failure
5 CONNECTION_FAILED Connection, socket or timeout failure
6 PROTOCOL_ERROR Unsupported or undecodable response
7 NOT_FOUND Requested target, setting or profile/transaction unavailable
8 PARTIAL_RESULT, or a partial result object Page/resource limit or incomplete operation
9 VERSION_MISMATCH Unsupported Collector version
10 IO_ERROR Artifact/transport I/O or integrity failure

A mid-response EOF currently maps to IO_ERROR (10), whereas socket exceptions/timeouts map to CONNECTION_FAILED (5). Exit 8 therefore needs both the exit status and the envelope: it can carry available data or describe a failure without data. Treat unrecognized nonzero exits as failures rather than guessing a known category.

Local file failures and Collector transport I/O have distinct human-readable messages while retaining IO_ERROR (10). Integrity errors retain their specific messages. See capture recovery before retrying a failed file write; a .partial file is not a committed checkpoint.

Streaming commands

xlog search uses scouterctl.stream/v1 on its first start event:

{"type":"start","schemaVersion":"scouterctl.stream/v1","source":{...},"query":{...},"storageDateVerification":"unverified"}
{"type":"record","data":{...}}
{"type":"complete","executionComplete":true,"upstreamCoverage":"unknown","sampling":"unknown"}

The abbreviated objects illustrate event shape, not executable JSON fixtures. There are zero or more record events. record and complete events do not repeat schemaVersion; they inherit the stream schema from start.

With xlog search --include-text, each record adds service and error dictionary fields alongside the existing hashes. Dictionary entries have hash, text, and status. Missing entries have status: "unresolved" and text: null. A zero error hash yields error: null. Both dictionary fields are absent by default. Error text may contain sensitive values.

A successful stream has exactly one final complete event and exit 0. Failure after streaming starts ends with the scouterctl.error/v1 error object and a nonzero exit, without complete. Failure before streaming starts may emit only the error object. A page budget produces PARTIAL_RESULT and exit 8; earlier records must not be mistaken for the full query. A killed process or failed output transport may leave no terminal event.

A consumer should accept the stream schema, process records, then require both the final complete event and exit 0 before marking the query complete. Use capture and its checkpoints when resumable extraction is needed.

storageDateVerification: "unverified" means the CLI used the supplied XLog storage date without confirmation from the Collector. An incorrect date can produce an empty completed query. XLog capture reports the same field in its outer result envelope.

Online window queries reject offset mismatches against the reported Collector JVM zone before streaming or writing captures. doctor and collector status expose the property's ID and a client-rule offset with explicit provenance; unavailable metadata remains null. These checks do not verify the storage calendar. See Collector time zones.

counter history uses its own scouterctl.counter-stream/v1 schema with the same start/record/complete lifecycle. Its start includes the dated target and counter metadata, and records contain stored timestamps and numeric strings. See counter history for missing values, units and query limits.

counter export returns a single manifest result and writes JSONL chunk files. Its scouterctl.counter-capture/v1 format is separate from XLog captures. See resumable counter export for budgets, checkpoints and completion semantics.

Values and evolution

  • txid, gxid, caller, and cursor transaction IDs are decimal strings, including negative values and the full signed 64-bit range. Never convert them through a floating-point number.
  • Hashes, counts, durations and timestamps retain their command-defined numeric types and units. Timestamps such as endTime, from and to are epoch milliseconds; elapsed durations are milliseconds. Do not infer units from a display label.
  • JSON booleans are booleans, not strings. null is not interchangeable with 0, an empty string, an empty array or an absent field. For example, current: null means no selected context; updated: null is not an update count of zero. Dictionary status and text availability must be read together.
  • Object-member order and whitespace are not part of the format. Consumers must tolerate added fields at every object level while validating fields they use. The current capture-file reader is stricter; JSON output tolerance does not change the capture compatibility rules.
  • Removing/renaming existing fields, changing their type, units or meaning, or changing established event semantics requires a new affected output schema version and documented migration. Existing error codes and exit meanings must not be silently repurposed. Enum/status additions that require new interpretation also need an explicit compatibility decision rather than being assumed safe.
  • New commands and additive fields can be introduced without changing existing envelopes. Changing existing command syntax or defaults in a way that breaks scripts requires release notes and a migration path. This document does not promise indefinite support for every old release.

Use the command guides for command-specific fields and behavior, profile completeness for truncation signals, grouped SQL output for the optional profile summary schema, and architecture for presentation/serialization ownership. Core and application models do not own JSON envelopes or numeric process exit codes.