Observe and troubleshoot
Correlate business, apply, frontend, backend, workflow, usage, analytics, denial, and audit signals before choosing a safe recovery.
Correlate business, apply, frontend, backend, workflow, usage, analytics, denial, and audit signals before choosing a safe recovery.
Start with the narrowest failing scope and preserve the identifiers that join the platform's signals: business id, environment id, commit SHA or release tag, apply id, build id, workflow execution id, request id, and audit request id. Do not change state until the evidence identifies which ownership boundary is wrong.
business/.farthershore business show acme --format json
farthershore business status acme --format json
farthershore apply-timeline list acme --env all --format json
farthershore apply-timeline inspect acme <id-or-tag-or-pr-or-branch-or-sha> \
--env production \
--format json
business status combines lifecycle state, latest release, latest deployment,
edge publication, and a derived live flag. An apply entry is the evidence for
one Git-triggered build/compile/accept/publish attempt. Select by exact id or
release tag when possible; a short SHA can match more than one attempt.
If the target is a preview, use its explicit environment name on every command. Never compare a production result with an unlabelled preview result.
farthershore frontend status acme --format json
farthershore frontend status acme --env <environmentId> --format json
farthershore frontend status acme --env <environmentId> \
--ref "$(git rev-parse HEAD)" \
--wait \
--timeout 600 \
--format json
Frontend status reports the active release, pin state, recent releases, recent
builds, and build errors. For a Git-triggered build, --ref observes the latest
known build for that immutable source revision; it does not identify a specific
webhook delivery or start a build. Exact attempt proof requires a build id where
the trigger returned one. A successful contract apply and a successful frontend
build are distinct facts.
farthershore backend list acme --format json
farthershore business routes acme --env <environment> --format json
backend list shows concrete backend rows, transport, environment, and status.
The Business program declares logical backends, but each environment needs its
own concrete direct origin or tunnel. There is no generic backend health
command: prove health with the backend status plus a signed request through the
gateway, then inspect analytics and the backend application's own logs.
If a direct backend exists in another environment, bind the target environment explicitly rather than assuming the origin carries over:
farthershore backend bind acme <backend> \
--env <environment> \
--origin-url https://api.example.com \
--format json
Apply Timeline is the business-scoped workflow signal available to normal business operators. Where the current identity has internal workflow-inspector access, deeper workflow evidence is available:
farthershore workflows ls --business <businessId> --status FAILED --format json
farthershore workflows show <workflowExecutionId> --format json
The detail includes steps, events, and convergence. Do not assume every failed
workflow is replayable. workflow-control replay is a billing replay preview,
not a general workflow retry, and workflow-control rollback-to-config is only
a rollback preview. Use the purpose-built business rollback only for a prior
publish workflow and only after reviewing its safety boundary.
farthershore usage summary acme --format json
farthershore analytics log acme --range 1h --domain usage --format json
farthershore analytics timeseries acme --range 24h --domain usage --format json
farthershore analytics latency acme --range 1h --format json
Analytics defaults to production. Pass --env <environmentId> for a preview;
there is deliberately no implicit all-environment aggregate. Request latency is
end to end, including the business backend, so high latency alone does not
locate platform overhead.
For a rejected request, preserve its request id:
farthershore denial show acme <requestId> --format json
The denial explanation identifies the enforced constraint and observed value. Decide whether the remedy is a repository change, a correct resource-count or usage report, or no change because the denial is expected. Do not raise a limit merely to hide a reporting bug.
farthershore audit-log business-list <organizationId> <businessId> \
--from 2026-08-08T00:00:00Z \
--format json
Filter further with --action, --actor, or --decision. Audit rows establish
the actor, action, decision, request, and time; they do not replace the current
business, apply, or frontend read-back.
| Evidence | Likely boundary | Safe next action | Completion evidence |
|---|---|---|---|
| Local build fails | Repository contract | Fix business/; rebuild | Local build succeeds |
| Apply build/compile fails | Repository or build input | Fix and push a new commit | New apply passes for the exact SHA |
| Apply accepted, edge publish failed | Platform publication | Preserve apply id; retry only the documented operation or escalate | Edge phase succeeds and expected request serves |
| Frontend build failed | Frontend source/build variables | Fix and push; use frontend status --ref "$(git rev-parse HEAD)" --wait | Build succeeds and expected release is active |
| Wrong frontend is live | Platform frontend pointer | Confirm target, then farthershore frontend rollback | Status shows the reviewed release id and pin |
| Direct backend unreachable | Per-environment backend binding or backend app | Verify the exact environment origin, signing verification, and app logs | Signed gateway request succeeds |
| Tunnel not ready | Tunnel provisioning/runtime | Inspect backend status and tunnel process; do not replace it with an unrelated direct origin | Backend ready and gateway request succeeds |
| Request denied | Repo policy, plan state, or reported operational usage | Inspect denial show; fix the owning fact | Same intended request is allowed, or expected denial is documented |
| Usage missing | Backend reporting or ingestion | Compare gateway request, analytics log, meter dimensions, and usage summary | One correlated request appears with the intended dimensions |
| Publish workflow failed | Publish workflow or downstream provider | Inspect Apply Timeline/workflow detail; fix source or use the exact recovery command | Replacement apply converges |
farthershore frontend rollback acme --release-id <releaseId> changes only
the hosted frontend pointer and pins it. It does not roll back the Business
contract, plans, billing, or backend. Later builds do not autoactivate while
pinned; activate a reviewed successful forward-fix release id explicitly with
the same command and verify status. There is no separate unpin command.farthershore business rollback acme <workflowExecutionId> --reason "..." starts an asynchronous rollback of one eligible prior publish workflow.
The returned workflow id proves enqueue, not convergence; inspect it and read
business status afterward.Stop mutating and preserve the evidence when:
Report the smallest reproducible scope, UTC timestamps, business/environment, commit or release, apply/build/workflow/request ids, exact command, structured error code, and what changed immediately beforehand. Redact secrets; never rotate, revoke, delete, or roll back additional state merely to gather evidence.