[ClusterLabs] Antw: Coming in Pacemaker 2.0.3: crm_mon output changes

[Ken Gaillot]

On Tue, 2019-10-15 at 08:42 +0200, Ulrich Windl wrote:
> > > > Ken Gaillot <kgaillot at redhat.com> schrieb am 15.10.2019 um
> > > > 00:47 in
> 
> Nachricht
> <bb7ed08d2044a7ccc14bd986cdea709caadee9cb.camel at redhat.com>:
> > Hi all,
> > 
> > With Pacemaker 2.0.2, we introduced a new experimental option for
> > XML
> > output from stonith_admin. This was the test case for a new output
> > model for Pacemaker tools. I'm happy to say this has been extended
> > to
> > crm_mon and will be considered stable as of 2.0.3.
> > 
> > crm_mon has always supported text, curses, HTML, and XML output,
> > and
> > that doesn't change. However the command‑line options for those
> > have
> > been deprecated and replaced with new forms:
> > 
> > Old:                New:
> > ‑‑as‑xml            ‑‑output‑as=xml
> > ‑‑as‑html=FILE      ‑‑output‑as=html ‑‑output‑to=FILE
> > ‑‑web‑cgi           ‑‑output‑as=html ‑‑output‑cgi
> > ‑‑disable‑ncurses   ‑‑output‑as=text
> 
> I'd prefer "--output-format|output-fmt|format" over "--format-as",
> because I
> think it's more clear.

That's a good question, what it should be called. We chose --output-as
in 2.0.2 for stonith_admin, so that has some weight now. I think the
main reason was to keep it shorter for typing (there's no single-letter 
equivalent at the moment because there's not an obvious choice
available across all tools).

I'm open to changing it if there's a lot of demand for it, otherwise
I'd rather keep it compatible with 2.0.2.

> Accordingly I'd prefer "--output-file" over "--output-to".

I like the more generic meaning of this one. The new approach also
supports --output-to="-" for stdout (which is the default). One could
imagine adding some other non-file capability in the future.

> Why not replace "--weg-cgi" with "--output-format=cgi"?

CGI output is identical to HTML, with just a header change, so it was
logically more of an option to the HTML implementation rather than a
separate one.

With the new approach, each format type may define any additional
options to modify its behavior, and all tools automatically inherit
those options. These will be grouped together in the help/man page. For
example, the HTML option help is:

Output Options (html):
  --output-cgi                      Add text needed to use output in a CGI program
  --output-meta-refresh=SECONDS     How often to refresh
  --output-stylesheet-link=URI      Link to an external CSS stylesheet
  --output-title=TITLE              Page title

> > 
> > The new ‑‑output‑as and ‑‑output‑to options are identical to
> > stonith_admin's, and will eventually be supported by all Pacemaker
> > tools. Each tool may support a different set of formats; for
> > example,
> > stonith_admin supports text and xml.
> > 
> > When called with ‑‑as‑xml, crm_mon's XML output will be identical
> > to
> > previous versions. When called with the new ‑‑output‑as=xml option,
> > it
> > will be slightly different: the outmost element will be a
> > <pacemaker‑
> > result> element, which will be consistent across all tools. The old
> > XML
> 
> Why not as simple "status" element? "-result" doesn't really add
> anything
> useful.

We wanted the design to allow for future flexibility in how users ask
pacemaker to do something. The XML output would be the same whether the
request came from a command-line tool, GUI, C API client application,
REST API client, or any other future interface. The idea is that
<pacemaker-result> might be a response to a <pacemaker-request>.

<pacemaker-result> was also introduced with stonith_admin in 2.0.2, so
that carries some weight, but it was announced as experimental at the
time, so I'm open to changing the syntax if there's a clear preference
for an alternative.

> > schema remains documented in crm_mon.rng; the new XML schema will
> > be
> > documented in an api‑result.rng schema that will encompass all
> > tools'
> > XML output.
> > 
> > Beyond those interface changes, the text output displayed by
> > crm_mon
> > has been tweaked slightly. It is more organized with list headings
> > and
> > bullets. Hopefully you will find this easier to read. We welcome
> > any
> > feedback or suggestions for improvement.
> 
> Older versions use a mixture of space for indent, and '*' and '+' as
> bullets.
> A unified approach would be either to use some amount of spaces or
> one TAB for
> indenting consistently, maybe combined with a set of bullet
> characters for the
> individual levels of indent.
> 
> So "--bullet-list='*+'" and "--indent-string=..." could set such.

That's an interesting suggestion.

The new approach does use a consistent style, with 2-space indents (to
fit as much as possible in a screen width) and '*' bullets (with an
additional indent for each deeper level). Also all list headings are
First Cap ending with a colon (':'). Example:

Active Resources:
  * Clone Set: myclone-clone [myclone]:
    * Started: [ f20node1 f20node2 ]

Allowing the bullets and indents to be configurable are something that
could theoretically be done with new options to the text format.

> > The HTML output gains a new feature as well: it uses CSS
> > throughout,
> > rather than ancient HTML formatting, and you can provide a custom
> > stylesheet (via ‑‑output‑stylesheet‑link=URL) to control how the
> > page
> > looks.
> 
> As it only applies to HTML, why not "--html-style=URL". I think
> nobody will
> confuse this with providing the stylesheet literally as parameter...

All of the format options start with "--output-" so we can reserve
those option names across all tools.

The --output-* options are new in 2.0.3, so we can change them if
people prefer. We could change this one to "--output-stylesheet" or "
--output-html-stylesheet".

> > 
> > If you are a heavy user of crm_mon, we encourage you to test the
> > new
> > release (expected later this week) and let us know what you like
> > and
> > don't like. You don't have to upgrade a whole cluster to test
> > crm_mon;
> > you can install the new release on a test machine, copy the CIB
> > from
> > your cluster to it, and run it like:
> > CIB_file=/path/to/copied/cib.xml
> > crm_mon <options>. That won't work with curses output, but you can
> > test
> > text, HTML, and XML that way.
> 
> BTW: Can we rename "-?" (version) to "-V" and "-V" (verbose) to "-v"? 
> That'll
> be more standard.

Hmm, there's a long history for those. They could be baked into user
scripts and higher-level tools. I'd be reluctant to change them unless
at a major version number bump (3.0.0).

> The possible outputs of "-s" could be documented in greater detail,
> possibly
> allowing to query a specific resource (implementing some simple query
> language)
> would be great. Not only for "-s", but also for all other output.

For -s in particular, I hope to eventually deprecate it and replace it
with a separate tool. It's not particularly useful in its current form.
The new tool would have a lot more control and detail. (For those who
aren't familiar, "crm_mon -s" behaves like a service plugin for
monitoring systems such as nagios and icinga.)

We do have plans for new crm_mon options to select a single node or
resource (or set of particular ones), and a new option to select which
sections of the output are displayed. But those are at least one more
version away.

> Regards,
> Ulrich

-- 
Ken Gaillot <kgaillot at redhat.com>