Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: how to run services reliably and update service autorestart to service lifecycle. #541

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

IronCore864
Copy link
Contributor

@IronCore864 IronCore864 commented Dec 22, 2024

According to our discussion (internal doc, sorry), this is the first piece of the next few how-to guides for Pebble.

In this PR:

  • The “service autorestart” doc is renamed to “service lifecycle” and expanded to a more-detailed reference.
  • A new how-to guide "how to run services reliably" detailing health checks is created, and placed after “how to install”, as the second how-to doc.
  • Per David's suggestion, some of the causes of unreliability in the modern microservice world are listed, and which can be mitigated by health checks/Pebble are explained.
  • Per David's suggestion, a few words on "what health checks are not" are added, so that the users won't misuse this feature to run cronjobs.

See more details and outline in the above discussion doc.

@IronCore864 IronCore864 requested a review from dwilding December 24, 2024 01:46
@IronCore864 IronCore864 marked this pull request as ready for review December 24, 2024 01:46
@dwilding
Copy link
Contributor

Thank you for doing this! Before I work on a more detailed review, I have a few ideas about the overall contents:

  1. "Health checks" section - I think this section should have more prominence. So how about making each topic a separate subsection, instead of using bullets?

    Also in this section, I think we ought to make it obvious up-front that "health checks" are a combination of Pebble's feature + what the service author chooses to implement.

    Then within each topic we can say what we recommend the service to do. For example, in the topic "Identifying Dependent Service Failures", I really like what you wrote:

    A service’s health check can include checks to ensure it can connect to its database, message queue, or other required services.

    This is nice & clear advice about how to approach health checks on the service side.

  2. "Configuring health checks in Pebble" and "Restarting service on health check failure" sections - I'd probably combine these into a single section that is fully focused on how to configure a health check of HTTP type and restart the service when the health check fails.

    Since this is a how-to doc, it's OK to omit the different options for health checks. I think it's better to give a specific scenario, then link to the reference pages for people to understand the different options.

  3. "Demo service" and "Putting it all together" sections - I feel these are extremely helpful, and the health-check-sample-service idea is neat! Since these sections are more guided, I'd consider moving them to a tutorial instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants