[CI:DOCS] man pages: document some --format options #14386
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,17 +30,33 @@ Pretty-print container statistics to JSON or using a Go template | |
|
|
||
| Valid placeholders for the Go template are listed below: | ||
|
|
||
| | **Placeholder** | **Description** | | ||
| | --------------- | ------------------ | | ||
| | .ID | Container ID (truncated) | | ||
| | .ContainerID | Container ID (full hash) | | ||
| | .Name | Container Name | | ||
| | .CPUPerc | CPU percentage | | ||
| | .MemUsage | Memory usage | | ||
| | .MemUsageBytes | Memory usage (IEC) | | ||
| | .AvgCPU | Average CPU (full precision float) | | ||
| | .AVGCPU | Average CPU (formatted) | | ||
| | .CPU | Percent CPU (full precision float) | | ||
| | .CPUNano | CPU Usage, total, in nanoseconds | | ||
| | .CPUSystemNano | CPU Usage, kernel, in nanoseconds | | ||
| | .Duration | Same as CPUNano (FIXME: why?) | | ||
| | .MemLimit | Memory limit, in bytes | | ||
| | .MemPerc | Memory percentage | | ||
| | .NetIO | Network IO | | ||
| | .BlockIO | Block IO | | ||
| | .PIDS | Number of PIDs | | ||
| | .NetInput | Network Input | | ||
| | .NetOutput | Network Output | | ||
| | .BlockInput | Block Input | | ||
| | .BlockOutput | Block Output | | ||
| | .PIDs | Number of PIDs | | ||
| | .SystemNano | Current system datetime, nanoseconds since epoch | | ||
| | .UpTime | WTF? This is Duration (CPUNano) in human-readable form?? | | ||
| | .Up | Same as UpTime (FIXME: why?) | | ||
|
There was a problem hiding this comment. Two FIXMES and one WTH where I'd appreciate feedback There was a problem hiding this comment. UpTime looks like it is the value in /proc/uptime. Which RHEL describes as I don't see '{{.Up so I don't think we should document it. There was a problem hiding this comment.
Well, that's just the problem in a nutshell. Where are you looking, that you don't see First: it exists: $ bin/podman stats --no-reset --no-stream --format '{{.Up}}'
57.940104sSecond, and much more importantly, command-completion offers it as a suggestion: $ bin/podman stats --format '{{.'
{{.AVGCPU}} {{.CPUSystemNano}} {{.MemPerc}} {{.PIDS}}
{{.AvgCPU}} {{.CPU}} {{.MemUsageBytes}} {{.PIDs}}
{{.BlockIO}} {{.ContainerID}} {{.MemUsage}} {{.PerCPU}}
{{.BlockInput}} {{.ContainerStats. {{.Name}} {{.SystemNano}}
{{.BlockOutput}} {{.Duration}} {{.NetIO}} {{.UpTime}}
{{.CPUNano}} {{.ID}} {{.NetInput}} {{.Up}} <<<<<<<<<<<<<<
{{.CPUPerc}} {{.MemLimit}} {{.NetOutput}}Therefore, IMO, it should be documented. This is what I'm trying to do in #14046. Nobody has stepped in to document the FIXMEs in that PR, so I'm taking baby steps myself. There are some fields, like this one, that are way above my ability to explain. There was a problem hiding this comment. Oh, and $ bin/podman stats --no-reset --no-stream --format '{{.UpTime}}'
57.994023s
$ bin/podman exec -l cat /proc/uptime
10354051.09 78779541.56There was a problem hiding this comment. I got that from reading the code, but perhaps there is other mechanisms for setting it? There was a problem hiding this comment. Fine then I say we either eliminate these builtin functions or someone figure a way to not expose them Up and Uptime are two ways of returning the same thing (One is a string the other is a time format?). If these become part of the docs, then we loose the ability to change their output. BlockInput versus BlockIO etc... There was a problem hiding this comment. Well, that's the premise behind #14046. As a dumb end user, if I type I realize this is a very low priority in the grand scheme of things. I would just like to have serious conversations about it, because if you look at #14046 you will see that we do a very, very poor job of documenting formats, and I think we can and should do better. Even if I have to abandon my cross-check, I would like to see some effort toward documenting. There was a problem hiding this comment. Sure. and I like the idea. The problem is we have leaked into this area fields we want users to use, along with fields we don't want them to use, and up to now, it was very unlikely they would discover the ones that leaked out. Which is why I don't want to document the mistake ones. There was a problem hiding this comment. Well how do you know what is internal and what not? At the moment there is no protection if a developer changes/removes fields. With @edsantiago script we could at least ensure that they are no unwanted breaking changes in the format templates. There was a problem hiding this comment. I want to look at the stats code and figure out if these functions are actually needed or not. Some of these are just translating from one form to another, but a conflict in names causes issues. Bottom line if we can not explain what a field is to the user then we should not document it. |
||
|
|
||
| When using a GO template, you may precede the format with `table` to print headers. | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this (string) (array of strings) (etc) useful?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it is unless it becomes overwhelming to the man page.