Re: [Nagios-devel] Nagios external commands (2)
Posted: Tue Sep 25, 2007 11:56 pm
Tobias Mucke wrote:
> Hi Andreas, hi list,
>
> thanks for this good thread and your time.
>
>>> Working with the External Commands documentation at nagios.org I got
>>> the impression that it is written manually and stored in some kind of
>>> content management system.
>> True. This must be so, or the docs might not match the reality in the
>> code.
>
> Hopefully, the docs do not match the reality in the code! There are
> some unlovely mistakes in it. Until today I thought this are just
> typos, because code and docs are maintained apart.
> My approach would be to maintain the XML file with two ideas behind.
>
> - it is an independent program understandable format describing the
> supported commands
Yes, but since Nagios can't use it (it needs to map the input to real
variables and memory addresses in-core), some documentation will still
need to be maintained.
> - it can be used to generate a more readable documentation
>
A worthy goal.
>>> With a XML file describing the Nagios
>>> External Command Interface you could generate the documentation e.g.
>>> by XSLT.
>>> Why should you do that? Because it would be possible to send patches
>>> for the documentation in a program understandable diff format.
>>>
>> But it already is. The program creating such program understandable diffs
>> is called (surprise, surprise) "diff". The program that understands those
>> diffs is called "patch".
>
> Surprise: I know these programs. And I would use them to send
> patches for the documentation. But I am not convinced that this will
> work fine. How to send patches for files generated by a content
> management system?
> Besides that this would only correct the documentation not the API. I
> am convinced that documentation has to be generated out of the program
> code, so documentation always matches the API and every change to the
> API is reflected immediatly in the documentation. Other programs are
> using the API. How can they handle changes without changing the
> program code? With a format independent description of the API. These
> ideas result in: API -> description -> documentation.
>
>> Seriously though, like I said above, the docs need to be maintained along
>> with the code, or the doc-to-code relation might get broken for a certain
>> revision of either.
>
> Agreed, this is the right approach. But there is no description of the
> API yet, so I decided to start with it. In future the description
> should be generated automatically out of the API. That's why I think
> it is important to Nagios and this mailing list.
>
Adding some auto-documentation feature about the API would have to be done
in the nagios core. Getting the nagios core to read XML files in order to
validate its input is totally pointless, because it still needs to use a
second and much stricter validation when it maps the input to the variables.
Getting the second, and stricter, validation to generate its documentation
is an exercise in futility, because it will be a lot harder to get right
than just updating the docs.
>>> Actually we are going to work on a concept for an even more
>>> distributed environment. Right now all distributed monitoring systems
>>> are located at one datacenter location. But we want to roll out Nagios
>>> to other datacenters at remote locations too. The idea is to give the
>>> remote datacenter as much as autonomy as possible e.g. keep
>>> notifications local at each location.
>> Sounds like a good idea. I'd use a NEB to propagate the commands if I
>> were you, or a separate program altogether.
>
> What about NEBs, are they incorporated within the Nagios code base
> after some discussions and code quality reviews, e.g. like kernel
> modules?
>
No. They're free-floating projects. Nagios has no method of linking any
modules into its core.
>>> Nethertheless we want just one central console to control the Nagios
>>> infrastructure, for example to enable / disable notifications. So you
>>> have to control Nagios by an interface you can send commands to from a
>>> central system. These commands should be checked if they are
...[email truncated]...
This post was automatically imported from historical nagios-devel mailing list archives
Original poster: [email protected]
> Hi Andreas, hi list,
>
> thanks for this good thread and your time.
>
>>> Working with the External Commands documentation at nagios.org I got
>>> the impression that it is written manually and stored in some kind of
>>> content management system.
>> True. This must be so, or the docs might not match the reality in the
>> code.
>
> Hopefully, the docs do not match the reality in the code! There are
> some unlovely mistakes in it. Until today I thought this are just
> typos, because code and docs are maintained apart.
> My approach would be to maintain the XML file with two ideas behind.
>
> - it is an independent program understandable format describing the
> supported commands
Yes, but since Nagios can't use it (it needs to map the input to real
variables and memory addresses in-core), some documentation will still
need to be maintained.
> - it can be used to generate a more readable documentation
>
A worthy goal.
>>> With a XML file describing the Nagios
>>> External Command Interface you could generate the documentation e.g.
>>> by XSLT.
>>> Why should you do that? Because it would be possible to send patches
>>> for the documentation in a program understandable diff format.
>>>
>> But it already is. The program creating such program understandable diffs
>> is called (surprise, surprise) "diff". The program that understands those
>> diffs is called "patch".
>
> Surprise: I know these programs.
And I would use them to send> patches for the documentation. But I am not convinced that this will
> work fine. How to send patches for files generated by a content
> management system?
> Besides that this would only correct the documentation not the API. I
> am convinced that documentation has to be generated out of the program
> code, so documentation always matches the API and every change to the
> API is reflected immediatly in the documentation. Other programs are
> using the API. How can they handle changes without changing the
> program code? With a format independent description of the API. These
> ideas result in: API -> description -> documentation.
>
>> Seriously though, like I said above, the docs need to be maintained along
>> with the code, or the doc-to-code relation might get broken for a certain
>> revision of either.
>
> Agreed, this is the right approach. But there is no description of the
> API yet, so I decided to start with it. In future the description
> should be generated automatically out of the API. That's why I think
> it is important to Nagios and this mailing list.
>
Adding some auto-documentation feature about the API would have to be done
in the nagios core. Getting the nagios core to read XML files in order to
validate its input is totally pointless, because it still needs to use a
second and much stricter validation when it maps the input to the variables.
Getting the second, and stricter, validation to generate its documentation
is an exercise in futility, because it will be a lot harder to get right
than just updating the docs.
>>> Actually we are going to work on a concept for an even more
>>> distributed environment. Right now all distributed monitoring systems
>>> are located at one datacenter location. But we want to roll out Nagios
>>> to other datacenters at remote locations too. The idea is to give the
>>> remote datacenter as much as autonomy as possible e.g. keep
>>> notifications local at each location.
>> Sounds like a good idea. I'd use a NEB to propagate the commands if I
>> were you, or a separate program altogether.
>
> What about NEBs, are they incorporated within the Nagios code base
> after some discussions and code quality reviews, e.g. like kernel
> modules?
>
No. They're free-floating projects. Nagios has no method of linking any
modules into its core.
>>> Nethertheless we want just one central console to control the Nagios
>>> infrastructure, for example to enable / disable notifications. So you
>>> have to control Nagios by an interface you can send commands to from a
>>> central system. These commands should be checked if they are
...[email truncated]...
This post was automatically imported from historical nagios-devel mailing list archives
Original poster: [email protected]