docs: add logging stub clarifying silent-by-design posture#6
Merged
Conversation
Short stub documenting that cgminer_api_client has no Logger module and emits no structured log events — it raises on failure (ConnectionError, SocketReadTimeout, etc.) and returns MinerResult/PoolResult on success. Callers (cgminer_monitor, cgminer_manager, the operator CLIs) own the log call sites. Points at cgminer_monitor/docs/log_schema.md as the cross-repo source of truth for the structured-log contract, and names the monitor-side events (poll.miner_failed, poll.unexpected_error) that surface api_client's public exception-class hierarchy via their `error:` key. Also notes that the CLI's -v/--verbose flag prints to stderr for operator debugging and is NOT a structured-log contract.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/logging.md(~25 lines) stating the design intent explicitly:cgminer_api_clienthas noLoggermodule and emits no structured log events. It raises on failure and returns result objects on success; callers own log emission.-v/--verboseflag is operator-facing stderr diagnostic output, not a structured-log contract (wire lines aren't JSON and shouldn't be piped to an aggregator).cgminer_monitor/docs/log_schema.mdas the cross-repo source of truth for the structured-log schema, and names the two monitor-side events (poll.miner_failed,poll.unexpected_error) whoseerror:key surfaces api_client's exception-class hierarchy.Scope
Part of the cross-repo structured-log-schema rollout. Companion PRs:
cgminer_monitorPR Attach structured cgminer_code and code symbol to ApiError #9 (canonicaldocs/log_schema.md+server.startshape flatten)cgminer_managerPR #24 (stub +elapsed_ms/render_ms→duration_ms)Land cgminer_monitor first so the cross-repo link resolves immediately.
Pure docs — no Ruby API change, no version bump.
Test plan
bundle exec rake— 226 examples, 0 failures; rubocop cleandocs/logging.mdon the GitHub PR diff view — cross-repo link resolves after cgminer_monitor PR Attach structured cgminer_code and code symbol to ApiError #9 merges