+list Il giorno 20/feb/2013 01:15, "Guido Trotter" <[email protected]> ha scritto: > > On Wed, Feb 20, 2013 at 12:12 AM, Michele Tartara <[email protected]> wrote: > > > > Il giorno 19/feb/2013 23:52, "Guido Trotter" <[email protected]> ha > > scritto: > > > > > >> > >> On Tue, Feb 19, 2013 at 11:49 PM, Guido Trotter <[email protected]> > >> wrote: > >> > On Tue, Feb 19, 2013 at 3:55 PM, Michele Tartara <[email protected] > > >> > wrote: > >> >> Update the monitoring agent design document adding the format of the > >> >> HTTP > >> >> queries that will have to be used to query the monitoring agent. > >> >> > >> >> Signed-off-by: Michele Tartara <[email protected]> > >> >> --- > >> >> doc/design-monitoring-agent.rst | 54 > >> >> ++++++++++++++++++++++++++++++++++++----- > >> >> 1 file changed, 48 insertions(+), 6 deletions(-) > >> >> > >> >> diff --git a/doc/design-monitoring-agent.rst > >> >> b/doc/design-monitoring-agent.rst > >> >> index 1d41e64..8bf691e 100644 > >> >> --- a/doc/design-monitoring-agent.rst > >> >> +++ b/doc/design-monitoring-agent.rst > >> >> @@ -48,12 +48,6 @@ The monitoring agent system will report on the > >> >> following basic information: > >> >> - Node OS resources report (memory, CPU, network interfaces) > >> >> - Information from a plugin system > >> >> > >> >> -Format of the query > >> >> -------------------- > >> >> - > >> >> -The query will be an HTTP GET request on a particular port. At the > >> >> -beginning it will only be possible to query the full status report. > >> >> - > >> >> Format of the report > >> >> -------------------- > >> >> > >> >> @@ -569,6 +563,54 @@ node RAID is outside the scope of this, and can be > >> >> implemented as a > >> >> plugin) but we can easily just report the information above, since > >> >> it's > >> >> standard enough across all systems. > >> >> > >> >> +Format of the query > >> >> +------------------- > >> >> + > >> >> +The queries to the monitoring agent will be HTTP GET requests on port > >> >> 1815. > >> >> +The answer will be encoded in JSON format and will depend on the > >> >> specific > >> >> +accessed resource. > >> >> + > >> >> +If a request is sent to a non-existing resource, a 404 error will be > >> >> returned by > >> >> +the HTTP server. > >> >> + > >> >> +The following paragraphs will present the existing resources supported > >> >> by the > >> >> +current protocol version, that is version 1. > >> >> + > >> >> +``/`` > >> >> ++++++ > >> >> +The root resource. It will return the list of the supported protocol > >> >> version > >> >> +numbers. > >> >> + > >> >> +Currently, this will include only version 1. > >> >> + > >> >> +``/1`` > >> >> +++++++ > >> >> +Not an actual resource per-se, it is the root of all the resources of > >> >> protocol > >> >> +version 1. > >> >> + > >> >> +If requested through GET, the null JSON value will be returned. > >> >> + > >> >> +``/1/full`` > >> >> ++++++++++++ > >> >> +The full report of all the data collectors, as described in the > >> >> section > >> >> +`Format of the report`_. > >> >> + > >> >> +`Status reporting collectors`_ will provide their output in > >> >> non-verbose format. > >> >> +The verbose format can be requested by adding the parameter > >> >> ``verbose=1`` to the > >> >> +request. > >> >> + > >> >> +``/[category]/[collector_name]`` > >> >> +++++++++++++++++++++++++++++++++ > >> >> +Returns the report of the collector ``[collector_name]`` that belongs > >> >> to the > >> >> +specified ``[category]``. > >> >> + > >> >> +If a collector does not belong to any category, ``collector`` will be > >> >> used as > >> >> +the value for ``[category]``. > >> >> + > >> >> +`Status reporting collectors`_ will provide their output in > >> >> non-verbose format. > >> >> +The verbose format can be requested by adding the parameter > >> >> ``verbose=1`` to the > >> >> +request. > >> >> + > >> > > >> > Why here we have verbose as a parameter and above we have "/full" as a > >> > resource that does the same thing? > >> > > >> > >> Never mind, I re-read it and now it's clear. (I was confused about /full). > > > > Ack. > > If you have a less confusing name to suggest, I'm glad to change it. > > > > How about /1/status ? > or /1/report ?
Status might seem to refer to the status data collectors only. Report does not say that we are going to reply with multiple reports. So, what about: /1/report/all for this and /1/report/[category]/[collector] for single reports? So we also obtain a more proper "namespace" separation at the first level after the version number and we do not mix commands and collector categories. > > >> I'm not entirely sure though about a couple of things: > >> > >> - there is no way to get a list of data collectors except by reading > >> the full report > > > > Right. I'll add it. > > > > Thanks. > > >> - there is no way to know which versions a data collector support > >> (true, now it's only "1") > > > > This is the version of the http API. Like the one for the RAPI daemon from > > where I took the idea. > > > > It only tells you how to invoke the various collectors. > > ACK. Note though that if we were to add version 2, are we sure no > collector would probably need modification? > If we're sure, then this doesn't matter. If we're not sure then it > might, as a collector might "support" both the old and the new way of > being invoked. Of course this might be moot at this point, as such a > resource can always be added later (eg. in version 2). > > > Data collectors don't need to explicitly support it. Only the monitoring > > agent. > > It is unrelated to the version of the output format of the specific > > collectors. > > > > Ack, for now. Note though that the fact that the collectors need or > don't need to support it depends on what the new version requires. :) I'm not sure about this. In my idea, the monitoring agent should be the only component responsible for receiving and decoding this queries. Then it invokes the collectors accordingly, passing whatever parameter is needed. But that is not, in my opinion, strictly part of the api. At most, of I understand, we could specify that every collector can receive additional collector-specific parameters as HTTP query parameters. And to let the users know what this parameters are, we might add either /1/version/[category]/[collector] returning the version of the specific collector (and therefore, implicitly, the list of parameters according to the collector documentation) or /1/params/[category]/[collector] explicitly returning the list of parameters accepted by the collector. This way we should obtain a complete decoupling between the specifics of the single collectors and the API version, that should, IMHO, only describe the "shape" of the query strings. > > >> - I am not entirely sure about /1/full VS > >> [category]/[collector_name]... should it be > >> 1/[category]/[collector_name] instead, for example? > > > > Of course. > > Just a typo: I probably deleted the initial /1/ while changing something. > > I'll add it back. > > > > Thanks, makes sense. > > Guido
