[Nagiosplug-devel] New Threshold Syntax

[Páll Guðjón Sigurðsson]

I appreciate the effort of putting this on github as it gives better view of the changes. I would personally love to limit the scope of that document to the threshold syntax only, so complexity does not grow out of control.

Other topics, like perfdata format do definitely go hand in hand with the threshold syntax, and a new spec for that should be drafted as well (but i prefer seperately to keep the new draft smaller and simpler).

There are new ideas in the spec since i implemented it in pynag. (like awarn,acrit,label,perf_label keywords) and some of these sound highly niche to me, and maybe (just maybe) they belong more to individual plugins to implement instead of the being in the threshold spec.

In any case i would propose to defer them to a later revision, when the new syntax has been established, and we can see for example if any of the official plugins would benefit from these keyworsd.

My two cents,
Palli

----- Original Message -----
From: "William Leibzon" <william at leibzon.org>
To: "Jochen Bern" <Jochen.Bern at linworks.de>
Cc: "Nagios Plugin Development Mailing List" <nagiosplug-devel at lists.sourceforge.net>
Sent: Thursday, September 5, 2013 7:33:34 PM
Subject: Re: [Nagiosplug-devel] New Threshold Syntax




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 

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 
------------------------------------------------------------------------------
Learn the latest--Visual Studio 2012, SharePoint 2013, SQL 2012, more!
Discover the easy way to master current and previous Microsoft technologies
and advance your career. Get an incredible 1,500+ hours of step-by-step
tutorial videos with LearnDevNow. Subscribe today and save!
http://pubads.g.doubleclick.net/gampad/clk?id=58041391&iu=/4140/ostg.clktrk
_______________________________________________________
Nagios Plugin Development Mailing List Nagiosplug-devel at lists.sourceforge.net
Unsubscribe at https://lists.sourceforge.net/lists/listinfo/nagiosplug-devel
::: Please include plugins version (-v) and OS when reporting any issue. 
::: Messages without supporting info will risk being sent to /dev/null