docs: describe cluster lifecycle states on the clusters concept page - #38629
Open
maheshwarip wants to merge 3 commits into
Open
docs: describe cluster lifecycle states on the clusters concept page#38629maheshwarip wants to merge 3 commits into
maheshwarip wants to merge 3 commits into
Conversation
Add a "Lifecycle of a cluster" section that names the states a cluster's replicas move through (provisioning, hydrating, catching up, steady state) and, for each, recommends the system-catalog relation to monitor progress. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015919agXAtbTfF1iHNpGQoj
Add documentation-authoring guidance to run doc SQL against the Materialize emulator before committing, and to include both the query and its verified output in syntax demos. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015919agXAtbTfF1iHNpGQoj
…ates Expand the "Lifecycle of a cluster" section with an example monitoring query and its sample output for each state (provisioning, hydrating, catching up, steady state). All output was captured from a running Materialize emulator. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015919agXAtbTfF1iHNpGQoj
Contributor
Author
|
Hey @antiguru would love your eyes on this PR - lmk if you disagree with this framework! Trying to put together something quick & lightweight to help users understand the lifecycle of a cluster |
antiguru
approved these changes
Sep 3, 2026
antiguru
left a comment
antiguru
left a comment
Member
There was a problem hiding this comment.
I think this is fine, but might need future revisions as we learn more. Let's notd block on what might be true in the future!
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
3 participants
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
It is not obvious from the docs that a cluster moves through distinct lifecycle states, nor how to tell whether it is making progress (vs. stuck) in each one. This came out of a Slack discussion on cluster lifecycle and freshness/"total lag":
https://materializeinc.slack.com/archives/CU7ELJ6E9/p1788365831558719?thread_ts=1788365056.126659&cid=CU7ELJ6E9
Description
Adds a Lifecycle of a cluster section to the clusters concept page. It briefly describes the states a cluster's replicas move through and, for each state, recommends how to monitor progress:
mz_cluster_replica_statusesandmz_clusters.mz_hydration_statuses(andmz_compute_hydration_statusesfor indexes/materialized views).mz_wallclock_global_lag_recent_historyandmz_materialization_lag.A note also points to the snapshotting step sources go through on first start.
Verification
Docs-only change. Verified all system-catalog and concept-page links resolve against the repo, and ran
bin/format-docs(no changes).🤖 Generated with Claude Code
https://claude.ai/code/session_015919agXAtbTfF1iHNpGQoj
Generated by Claude Code