docs: clarify /healthz and /readyz #11085
Conversation
github-actions
bot
requested review from
codingllama,
fheinecke,
ptgott,
r0mant and
xinding33
| @@ -15,27 +15,9 @@ run with verbose logging enabled by passing it `-d` flag. | |||
| It is not recommended to run Teleport in production with verbose logging as it generates a substantial amount of data. | |||
| </Admonition> | |||
|
|
|||
| Sometimes you may want to reset [`teleport`](../reference/cli.mdx#teleport) to a clean | |||
There was a problem hiding this comment.
Removed this section, as it was a duplicate of whats in metrics.mdx.
IMO, the troubleshooting page should be focused on "things aren't working, what steps can I take to fix them" and metrics is more focused on "how can I monitor to ensure things are operating correctly and detect when things start to go wrong."
zmb3
force-pushed
the
zmb3/docs-readyz
branch
2 times, most recently
from
5765b2b to
0a199b1
Compare
There was a problem hiding this comment.
Since this is the only docs page that mentions the heartbeat, I've recommend separating the heartbeat discussion into a subsection below the "/readyz" section to provide the authoritative description of it.
Is the heartbeat used for more than diagnostics/telemetry (e.g., load balancing)? If it is, it might make sense to talk about the heartbeat in its own page of the docs (e.g., in the Architecture section).
What do you think?
|
|
||
| - HTTP 200 OK: Teleport is operating normally | ||
| - HTTP 503 Service Unavailable: Teleport has encountered a connection error and | ||
| is running in a degraded state. This happens when a Teleport heartbeat fails. |
There was a problem hiding this comment.
Since (as far as I can tell) this is the first time we discuss the heartbeat in the docs, should we introduce the heartbeat at the beginning of the "/readyz" section? E.g., which component sends heartbeat traffic to other components and what port and protocol the heartbeat uses.
We cover some of this in the "Recovery" Admonition, but I think it makes sense to introduce this before we first mention the status object.
| The same state information is also available via the `process_state` metric | ||
| under the `/metrics` endpoint. | ||
|
|
||
| <Admonition type="note" title="Recovery"> |
There was a problem hiding this comment.
I think we can add an H4 section called "Heartbeat" (or similar) to the top of the "/readyz" section, then move this text to that H4 section. Then we can add another H4, "Status object" (or similar), which contains the information in "/readyz" that isn't in this Admonition.
I think it would be easier this way for a reader to get familiar with the heartbeat before reading about the status object.
If we want to introduce heartbeats separately, it should probably be a separate page, as they're somewhat orthogonal to metrics. Do you think there's a minimal edit or two we can make here to get this merged and create a separate issue for documenting heartbeats? I'm not a fan of holding up a PR that may provide value now, even if there is still some confusion we need to address. |
- Rename the page, since it's about diagnostics rather than metrics alone - Change major section headings to H2s so they apper in the table of contents - Move information about heartbeats and recovery to an H3 so it's more visible - More information about status codes to a separate H3 below the H3 re: heartbeats, both for visibility and to help ensure the reader knows the relevant information about heartbeats first
|
Ok @ptgott - merged your suggestions, please take another look. |
- Rename the page, since it's about diagnostics rather than metrics alone - Change major section headings to H2s so they apper in the table of contents - Move information about heartbeats and recovery to an H3 so it's more visible Updates #10799 Co-authored-by: Paul Gottschling <[email protected]>
- Rename the page, since it's about diagnostics rather than metrics alone - Change major section headings to H2s so they apper in the table of contents - Move information about heartbeats and recovery to an H3 so it's more visible Updates #10799 Co-authored-by: Paul Gottschling <[email protected]>
- Rename the page, since it's about diagnostics rather than metrics alone - Change major section headings to H2s so they apper in the table of contents - Move information about heartbeats and recovery to an H3 so it's more visible Updates #10799 Co-authored-by: Paul Gottschling <[email protected]>
- Rename the page, since it's about diagnostics rather than metrics alone - Change major section headings to H2s so they apper in the table of contents - Move information about heartbeats and recovery to an H3 so it's more visible Updates #10799 Co-authored-by: Paul Gottschling <[email protected]> Co-authored-by: Paul Gottschling <[email protected]>
- Rename the page, since it's about diagnostics rather than metrics alone - Change major section headings to H2s so they apper in the table of contents - Move information about heartbeats and recovery to an H3 so it's more visible Updates #10799 Co-authored-by: Paul Gottschling <[email protected]>
- Rename the page, since it's about diagnostics rather than metrics alone - Change major section headings to H2s so they apper in the table of contents - Move information about heartbeats and recovery to an H3 so it's more visible Updates #10799 Co-authored-by: Paul Gottschling <[email protected]> Co-authored-by: Paul Gottschling <[email protected]>
- Rename the page, since it's about diagnostics rather than metrics alone - Change major section headings to H2s so they apper in the table of contents - Move information about heartbeats and recovery to an H3 so it's more visible Updates #10799 Co-authored-by: Paul Gottschling <[email protected]> Co-authored-by: Paul Gottschling <[email protected]>
Backports required:
Updates #10799