[Nagiosplug-devel] New Threshold Syntax

[William Leibzon]

This was very valuable feedback on current proposal spec  I really
appreciate Jochen going through it. My reply in regards to the feedback is
below and I modified proposal text based on the feedback. Latest version
can be found at:


https://github.com/willixix/nagios-plugins/wiki/Draft-Proposal:-Nagios-Plugins-Development-Guidelines-and-Threshold-Syntax-Specification-2.0

<https://github.com/willixix/nagios-plugins/wiki/Draft-Proposal:-Nagios-Plugins-Development-Guidelines-and-Threshold-Syntax-Specification-2.0>On
Wed, Aug 21, 2013 at 11:31 AM, Jochen Bern <Jochen.Bern at linworks.de> wrote:

> On 21.08.2013 17:23, William Leibzon wrote:
> > I have requested time at upcoming Nagios conference for 30 minute BoF
> > session on this topic and to get feedback on any general features people
> > may like to see in all the plugins. They have't got back to me yet (only
> > sent email on Friday) but this is not a formal session and so I'd not
> > expect an issue with holding it after normal sessions are over.
> >
> > My own plugins library and several plugins will support the syntax at
> > https://github.com/willixix/nagios-plugins/wiki/New-Threshold-Syntax by
> > conference time (just committed most of the necessary code yesterday).
>
> I'm afraid I haven't had much time to read up on the discussion ever
> since my first reply on the topic (which I made from a cell phone with
> an almost-depleted battery, so I'm sorry if I sounded a bit gruff), so
> let me take this opportunity to comment on the version currently on that
> page:
>
> -------
>
> I'm missing the possibility to supply *different* labels for the same
> (numerical) data as presented in the output vs. in the performance data.
> Cases where such a differentiation would be useful, off the top of my head:
> -- Output (-> notifications) in local staff's primary language, but
>    perfdata names shall be in English so as to permit *global*
>    referencing (say, in a performance data backend system's graph
>    templates)
>    [Same goes for things like "Houston Interlink" vs. "Interface 4711",
>    "upstream"/"downstream" vs. "ingress"/"egress", etc. ad nauseam]
>

I already before added "label" for re-naming data which is meant to be both
for status output and perf data. Per you suggestion I now also add
"perf_label" that would allow to re-name only perf data label. I think
these uses would be quite irregular, but we can allow for it.


> -- Continuity of saved performance data, e.g., what the first version
>    of the plugin reported as "rx pkts" should now be properly called
>    "received unicast packets to a local MAC" in the output but still
>    just "rx_pkts" in the performance data
>
> Note 1: It would be a possibility to use non-{yes_or_no} values for the
>         "display" and/or "perf" keywords to achieve this.
>

What is wrong with "yes" and "no"?


> Note 2: There are performance data backends which rely on the *order*
>         of performance data items, rather than their naming, to have
>         performance data items produced by the current plugin run
>         correlated to (hopefully) equivalent items of the previous
>         runs. Do we want to provide a means, however contrived, to
>         control that order?
>

I added "order" keyword. But I think plugins should basically process
threshold in the same order they are at the options line. That is at least
what my own library does and it allows to specify order too but in
different way.


> Note 3: Restricting the labels to [A-Za-z0-9_-]* means that we're
>         actually dropping behind the current perfdata spec (which allows
>         special chars inside quotes).
>

That is an oversight in draft text. Full range of ascii symbols should be
supported for metric name with quotes used just like in current spec.
However when creating custom perfdata label I think restricting set of
symbols is better.


>
> -------
>
> rrdtool, as the most common basis for performance data backends, allows
> you to provide a non-numerical value 'c so that you can provide
> complete data*sets* even in cases where single *values* are unknown /
> cannot be determined. PNP4Nagios followed suit and now allows plugins to
> return 'U' in the performance data (replacing the number, still allowing
> the UOM etc.). I think this should make it into an updated perfdata spec
> (which is likely to result from *this* activity sooner rather than later).
>

I added this into spec proposal now too. In case "absent" keyword is
present, the plugin should return U in performance data.


> -------
>
> Speaking of the UOM, your spec for the "uom" keyword mirrors the current
> perfdata specs in only allowing UOMs from a given whitelist. [Yes, I'm
> aware that the allowed values for your "uom" keyword do not necessarily
> imply restrictions on the UOM spec for plugin output, but bear with me.]
>
> This approach has, in my opinion, proven to be a failure because it is
> virtually impossible to provide an all-encompassing list of UOMs that
> may occur in the wild. (Off the top of my head, I have "ppm" from ntpd
> drift files, several UOMs for bandwidth, "dBm" for GSM reception level,
> "degC" for Temperatures, "RPM" for fans, "V" for Voltages, ...) One
> consequence of that is that I do not know a *single* perfdata backend
> that would try to split the perfdata UOM back into unit and prefix, and
> *that* results in output (graphs) where UOMs like "kB" (as output by
> "df", for example) get scaled into "MkB" and similar chimeras. Thus, my
> first suggestion: Drop the ever-outdated base unit registry!


As far as I know PnP and other backends do clearly differentiate 'c' from
anything else which they just treat as custom label or not support at all.
It is true that multipliers "k", "m", etc are not currently differentiated
and perhaps if we make it clear these are si units they will start to be
used. I modified proposal text to specify how custom labels can be
supported and how to differentiate SI ranges as part of that. Please
everyone go through this.

Second, if we want a chance to *ever* get proper automatic UOM scaling
> back in working order, we need some sort of hint within the perfdata UOM
> string that allows the backends to tell prefix from base unit, candela
> from centidays, Ampere- from attohours, etc.. I'm thinking of a
> separator character, preferably one that results in a small, unobtrusive
> representation if *not* caught before Web-UI etc.. (U+00B7 looks like a
> good candidate to me, but I'm not very experienced with charset
> conversion and compatibility problems ...)
>

I added two way to do it. One is with a single one-letter UOM followed by
custom unit name and 2nd is by specifying full NIST prefix name followed by
'-' and then unit name.


>
> -------
>
> The "prefix" keyword *badly* needs a clarification where it shall have
> an effect and where not:
>

My understanding of original proposal is that PREFIX keyword would only
effect how data is scaled when plugin does status line output. UOM keyword
is used both for both labeling and scaling of data when output goes into
performance data. Perhaps these two should be combined or separated
differently. Please let me know.

The actual list of valid prefixes and how to create custom UOMs and
differentiate them should all be more clear from updated text.

-- prefixed to string specified with "uom" keyword
> -- causing the relevant number output to be rescaled
>    -- *from* prefixed *to* prefixless UOM
>       (i.e., "prefix:k" changes original result "3.14" to "3140",
>       equivalent to the statement "the number obtained by the plugin
>       up to output formatting *is in* thousands")
>    -- *from* prefixless *to* prefixed UOM
>       (i.e., when the plugin's original output is "4711 foo",
>       "prefix:k" shall change it to "4.7 kfoo"
> -- causing the *thresholds* to be rescaled accordingly
>    -- again, *from* or *to* the given prefix
> and most of this could potentially apply to a number's representation in
> the output, the perfdata, or both ...
>
> Kind regards,
>                                                                 J. Bern
> --
> *NEU* - NEC IT-Infrastruktur-Produkte im <http://www.linworks-shop.de/>:
> Server--Storage--Virtualisierung--Management SW--Passion for Performance
> Jochen Bern, Systemingenieur --- LINworks GmbH <http://www.LINworks.de/>
> Postfach 100121, 64201 Darmstadt | Robert-Koch-Str. 9, 64331 Weiterstadt
> PGP (1024D/4096g) FP = D18B 41B1 16C0 11BA 7F8C DCF7 E1D5 FAF4 444E 1C27
> Tel. +49 6151 9067-231, Zentr. -0, Fax -299 - Amtsg. Darmstadt HRB 85202
> Unternehmenssitz Weiterstadt, Geschäftsführer Metin Dogan, Oliver Michel
>

Thanks again for the feedback,

William
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://nagios-plugins.org/archive/devel/attachments/20130905/f3ac2787/attachment.html>