Add "Using Pebble" documentation to README #162
Conversation
| @@ -9,7 +9,7 @@ designed with unique features that help with more specific use cases. | |||
|
|
|||
There was a problem hiding this comment.
The first few lines should say (1) what Pebble is, (2) what it does, (3) what problem it solves, and (4) who it's useful for. The current write-up is great but seems to cover only point (3).
There was a problem hiding this comment.
Thanks for looking at the doc as a whole, and I agree this could use improvement. However, the scope of this PR is just adding the "Using Pebble" documentation, so I'm going to leave this for another PR.
| @@ -118,26 +118,248 @@ services: | |||
| command: cmd | |||
| ``` | |||
|
|
|||
There was a problem hiding this comment.
Regarding the configuration examples: They are great but should be given in addition to the spec, not instead of it. Otherwise we find ourselves wanting to supplement as in "Some details worth highlighting". So, please consider giving the actual spec, answering questions like "What are all the fields, features, values, etc., possible in this file?" You could adopt a format like https://juju.is/docs/sdk/metadata-yaml or, maybe better, https://juju.is/docs/sdk/charmcraft-yaml .
There was a problem hiding this comment.
I see you actually do give the full spec starting with line 359. It should be higher up and the examples should be nested under it.
There was a problem hiding this comment.
Yeah, that's right, the YAML spec is under "Layer specification" in the format of https://juju.is/docs/sdk/metadata-yaml -- I put it below "Using Pebble" as I felt reference material should be after the general "using Pebble" section.
README.md
Outdated
| * `tcp`: opening the given TCP port must be successful | ||
| * `exec`: executing the specified command must yield a zero exit code | ||
|
|
||
| Checks are configured in the layer configuration using the top-level field `checks`. Below is an example layer showing the three different types of checks: |
There was a problem hiding this comment.
This belongs in the layer configuration spec section. You can reference it from here. Or maybe have the generic spec there and a link to that + a concrete example here.
There was a problem hiding this comment.
I realize there's a bit of duplication here, however, I think it's important to know the check types up-front. But I've added a phrase and link to the full spec below.
| @@ -9,7 +9,7 @@ designed with unique features that help with more specific use cases. | |||
|
|
|||
| - [General model](#general-model) | |||
| - [Layer configuration examples](#layer-configuration-examples) | |||
| - [Running pebble](#running-pebble) | |||
| - [Using pebble](#using-pebble) | |||
| - [Layer specification](#layer-specification) | |||
There was a problem hiding this comment.
In the Table of Contents / the organization of the sections, please consider using Diataxis. That is, you should the 5 main sections below, with your existing sections nested within along the following lines (at least, at first glance):
- Home Introduction (the intro lines I mentioned above)
- Tutorial
- How-to guides
- Install (i.e., How to install Pebble)
- Set up (i.e., How to set up the Pebble directory)
- Use (i.e., How to use Pebble)
- Run the daemon (i.e., How to run the Pebble daemon)
- Start and stop services (i.e., How to start and stop Pebble services)
- Reference
- General model
- Layer configuration spec + examples
pebbleCLI- List of
pebbleCLI commands
- List of
- Service dependencies
- Health checks
- Changes and tasks
- ...
- Explanation
At first glance, all the materials you have are either How-to guides or Reference, so you can leave out the Tutorial and Explanation for now. As for how to organize How-to guides vs. Reference: I'd put any material that defines things into Reference and any material that gives instructions into How-to guides. I'd also try to organize the Reference docs around primitive concepts and bits and then the How-to guides also around that where, for a product that has a CLI, the how-to guides are usually about manipulating a primitive entity in various ways using various CLI commands. See, for example, https://juju.is/docs/olm/the-juju-client and https://juju.is/docs/olm/manage-juju, or https://juju.is/docs/olm/network-spaces and https://juju.is/docs/olm/manage-spaces , or https://juju.is/docs/olm/action and https://juju.is/docs/olm/manage-actions .
There was a problem hiding this comment.
This is a good discussion, however, it's a big structural change to the rest of the document -- I'm going to leave this for future work.
@barrettj12 I thought about this, but on balance I think I prefer it in a single file. If anything I think we could split out "Using Pebble" into |
README.md
Outdated
| ... | ||
| ``` | ||
|
|
||
| The daemon's service manager stores the most recent stdout and stderr from each service (using a 100KB ring buffer per service). These are accessible via the logs API or using `pebble logs`. If you want to also write service logs to Pebble's own stdout, run the daemon with `--verbose`: |
There was a problem hiding this comment.
This seems to be going too fast into debugging. Instead, we should be talking about the model: statuses, plan, changes, etc. Otherwise this smells like a boring process runner, instead of a nicely structured service support system.
To improve this, I suggest cutting off right before the run command output, continuing through the rest of the experience, and only later mentioning the ability to see logs.
Also, before we start/stop and change the state, let's talk about reading the current state that took place right after running.
There was a problem hiding this comment.
I agree the logging stuff was going too deep (and tangential) here -- fixed. I've added a separate sub-section "Logs" at the bottom of the "Using Pebble" section. Regarding "statuses, plan, changes, etc": We talk about the plan/config in the first section as mentioned, and changes and tasks in their own section below.
README.md
Outdated
| $ pebble stop srv1 # stop one service | ||
| ``` | ||
|
|
||
| When starting a service, Pebble records a "Start" [change](#changes-and-tasks) for the operation, executes the service's `command`, and waits 1 second to ensure the command doesn't exit too quickly. Assuming the command doesn't exit within 1 second, the start is considered successful, otherwise `pebble start` will exit with an error. |
There was a problem hiding this comment.
It seems premature to dive so deeply into the details of process management here. I'd reserve such details for an advanced section, and even then probably avoid promising things like exact timings as that can easily change.
There was a problem hiding this comment.
I'm refactored this section a little, but I disagree that this is too much detail here. This README is what we have for a user manual right now, so I think it should explain it, not try to stuff important details in an "advanced" section.
I at first removed the exact timings, but the current timings are part of said user manual, and as such should be documented. I think it's important, otherwise if we say something like "waits a short time" users will be thinking, "Okay, but how long is short?"
README.md
Outdated
| * `backoff`: in a [backoff-restart loop](#service-auto-restart) | ||
| * `error`: in an error state (currently: exited and exit action is "ignore") | ||
|
|
||
| Implementation note: Pebble's service manager uses a [state machine](https://github.com/canonical/pebble/blob/a1f52239079e58cb6e3b6c7472ef5438b91eefab/internal/overlord/servstate/handlers.go#L67-L82) to manage the life cycle of a service. You can see these internal states and their transitions in the [state diagram](https://raw.githubusercontent.com/canonical/pebble/master/internal/overlord/servstate/state-diagram.svg). |
There was a problem hiding this comment.
Similar to the above point, we don't want to be documenting internal details of the implementation and pointing people to the code in a section that is intended for a new user that has never seen Pebble.
There was a problem hiding this comment.
Fair -- I've removed this paragraph.
This PR adds a large section of documentation to the README about how to use Pebble, and how some of its major features work. This is intended as a mini user manual; several people have asked about how these things work, and I've previously had to say "sorry, it's documented in the code". :-)