Docs: correct the v0.6.0 upgrade notes and recommend alerts - #87
Merged
Merged
Conversation
The Upgrading note that `yabeda-hotcell` writes no log line misled readers once `HotCell::LogSubscriber` shipped. The README's "Logs" section covered only the cell's logs. Rename it "Cell logs", move `HotCell::LogSubscriber` into an "Application logs" section beside it, rewrite the Upgrading notes as action-and-rationale pairs and add one for the health controllers, and shorten entries that repeated the README.
The README's observability section described each signal but not what to alert on, and its advice was spread across three sections. Add a "Recommended alerts" section from the guidance in #64, and point at `docs/LOGS.md` and `docs/TUNING.md` for the rest. `docs/TUNING.md` said to watch `queue_high_water` near `queue_size`, but that value resets only at boot, so name `queued` and a rise in `queue_high_water` instead. [Fix #64]
Give each sentence a subject that can do what its verb says, and cut words that carried nothing.
The README and CHANGELOG said "Your application adds the routes", which described the reader rather than the gem. Say that `hotcell-client` defines the controllers and does not define routes for them.
The README and CHANGELOG said what `hotcell-client` does not do. Say what the application should do: add a route for each controller, and put the diagnostics route behind authentication.
The README and CHANGELOG text added since v0.5.0 used marketing verbs, described the reader instead of the software, and put several statements in one sentence. Rewrite it in ASD-STE100: one statement per sentence, active voice, and instructions in the imperative.
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
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.
Motivation
The
next / unreleasedUpgrading section ofCHANGELOG.mdsaysyabeda-hotcell"does not write a log line for each call". That was written before #78 addedHotCell::LogSubscriber, which does write one. An application whose own Yabeda integration also logs each call would log every call twice after following that note.The README's Observability section titles the cell's stdout "Logs", while the application's log line sits under "Per-call telemetry". It also describes each signal without saying what to alert on, which #64 asks for.
Details
HotCell::LogSubscriberdocs into an "Application logs" section beside it, with the non-Rails setup that was only in the CHANGELOG. "Per-call telemetry" now leads with theperform.hot_cellevent and names both subscribers that ship.CONTRIBUTING.mdasks. Tell applications to remove their own log line wherever it is written, and add an item for replacing hand-built health endpoints withHotCell::HealthControllerandHotCell::DiagnosticsController.docs/LOGS.mdanddocs/TUNING.md.docs/TUNING.mdsaid to watchqueue_high_waternearqueue_size, but that value resets only at boot. It now namesqueuedand a rise inqueue_high_water.Fixes #64