On Tue, Mar 12, 2013 at 12:05 PM, Guido Trotter <[email protected]>wrote:
> On Tue, Mar 12, 2013 at 11:57 AM, Michele Tartara <[email protected]> > wrote: > > On Mon, Mar 11, 2013 at 7:10 PM, Guido Trotter <[email protected]> > wrote: > >> > >> On Mon, Mar 11, 2013 at 5:14 PM, Michele Tartara <[email protected]> > >> wrote: > >> > On Mon, Mar 11, 2013 at 5:04 PM, Guido Trotter <[email protected]> > >> > wrote: > >> >> > >> >> On Mon, Mar 11, 2013 at 4:53 PM, Michele Tartara < > [email protected]> > >> >> wrote: > >> >> > On Mon, Mar 11, 2013 at 4:22 PM, Iustin Pop <[email protected]> > >> >> > wrote: > >> >> >> > >> >> >> On Mon, Mar 11, 2013 at 04:11:48PM +0100, Michele Tartara wrote: > >> >> >> > This commit adds the design document for introducing "reason > >> >> >> > trails", > >> >> >> > tracing the reason why opcodes are executed, step by step. > >> >> >> > > >> >> >> > Signed-off-by: Michele Tartara <[email protected]> > >> >> >> > --- > >> >> >> > Makefile.am | 1 + > >> >> >> > doc/design-draft.rst | 3 +- > >> >> >> > doc/design-reason-trail.rst | 86 > >> >> >> > +++++++++++++++++++++++++++++++++++++++++++ > >> >> >> > 3 files changed, 89 insertions(+), 1 deletion(-) > >> >> >> > create mode 100644 doc/design-reason-trail.rst > >> >> >> > > >> >> >> > diff --git a/Makefile.am b/Makefile.am > >> >> >> > index 4020227..644e9f6 100644 > >> >> >> > --- a/Makefile.am > >> >> >> > +++ b/Makefile.am > >> >> >> > @@ -398,6 +398,7 @@ docinput = \ > >> >> >> > doc/design-partitioned.rst \ > >> >> >> > doc/design-query-splitting.rst \ > >> >> >> > doc/design-query2.rst \ > >> >> >> > + doc/design-reason-trail.rst \ > >> >> >> > doc/design-resource-model.rst \ > >> >> >> > doc/design-restricted-commands.rst \ > >> >> >> > doc/design-shared-storage.rst \ > >> >> >> > diff --git a/doc/design-draft.rst b/doc/design-draft.rst > >> >> >> > index 9dd2dfc..ec5303b 100644 > >> >> >> > --- a/doc/design-draft.rst > >> >> >> > +++ b/doc/design-draft.rst > >> >> >> > @@ -2,7 +2,7 @@ > >> >> >> > Design document drafts > >> >> >> > ====================== > >> >> >> > > >> >> >> > -.. Last updated for Ganeti 2.7 > >> >> >> > +.. Last updated for Ganeti 2.8 > >> >> > >> >> Nack on this part of the change. > >> >> (we only do this later, reviewing which docs have been implemented > and > >> >> moving them under the 2.8 document). > >> >> > >> > > >> > Ok. I didn't know it. I'll switch back to 2.7. > >> > > >> >> > >> >> >> > > >> >> >> > .. toctree:: > >> >> >> > :maxdepth: 2 > >> >> >> > @@ -17,6 +17,7 @@ Design document drafts > >> >> >> > design-monitoring-agent.rst > >> >> >> > design-hroller.rst > >> >> >> > design-storagespace.rst > >> >> >> > + design-reason-trail.rst > >> >> >> > > >> >> >> > .. vim: set textwidth=72 : > >> >> >> > .. Local Variables: > >> >> >> > diff --git a/doc/design-reason-trail.rst > >> >> >> > b/doc/design-reason-trail.rst > >> >> >> > new file mode 100644 > >> >> >> > index 0000000..8e86e88 > >> >> >> > --- /dev/null > >> >> >> > +++ b/doc/design-reason-trail.rst > >> >> >> > @@ -0,0 +1,86 @@ > >> >> >> > +=================== > >> >> >> > +Ganeti reason trail > >> >> >> > +=================== > >> >> >> > + > >> >> >> > +.. contents:: :depth: 2 > >> >> >> > + > >> >> >> > +This is a design document detailing the implementation of a way > >> >> >> > for > >> >> >> > Ganeti to > >> >> >> > +track the origin and the reason of every executed command, from > >> >> >> > its > >> >> >> > starting > >> >> >> > +point (command line, remote API, some htool, etc.) to its > actual > >> >> >> > execution > >> >> >> > +time. > >> >> >> > + > >> >> >> > +Current state and shortcomings > >> >> >> > +============================== > >> >> >> > + > >> >> >> > +There is currently no way to track why a job and all the > >> >> >> > operations > >> >> >> > part of it > >> >> >> > +were executed, and who or what triggered the execution. > >> >> >> > +This is an inconvenience in general, and also it makes > impossible > >> >> >> > to > >> >> >> > have > >> >> >> > +certain information, such as finding the reason why an instance > >> >> >> > last > >> >> >> > changed its > >> >> >> > +status (i.e.: why it was started/stopped/rebooted/etc.), or > >> >> >> > distinguishing > >> >> >> > +an admin request from a scheduled maintenance or an automated > >> >> >> > tool's > >> >> >> > work. > >> >> >> > + > >> >> >> > +Proposed changes > >> >> >> > +================ > >> >> >> > + > >> >> >> > +We propose to introduce a new piece of information, that will > be > >> >> >> > called > >> >> >> > "reason > >> >> >> > +trail", to track the path from the issuing of a command to its > >> >> >> > execution. > >> >> >> > + > >> >> >> > +The reason trail will be a list of pairs ``(source, reason)``, > >> >> >> > with: > >> >> >> > + > >> >> >> > +``source`` > >> >> >> > + The entity deciding to perform (or forward) a command. > >> >> >> > + It is represented by an arbitrary string, but strings > prepended > >> >> >> > by > >> >> >> > "gnt:" > >> >> >> > + are reserved for Ganeti components, and they will be refused > by > >> >> >> > the > >> >> >> > + interfaces towards the external world. > >> >> >> > + > >> >> >> > +``reason`` > >> >> >> > + The reason why the entity decided to perform the operation. > >> >> >> > + It is represented by an arbitrary string. > >> >> >> > >> >> >> You forgot the timestamp… > >> >> > > >> >> > > >> >> > Actually, it was intentionally omitted, because it seems to me that > >> >> > we > >> >> > were > >> >> > not 100% sure that a timestamp at each step was needed. > >> >> > But I'll add it, no problem. :-) > >> >> > > >> >> >> > >> >> >> > +The reason trail will be attached at the OpCode level and will > be > >> >> >> > kept > >> >> >> > as a list > >> >> >> > +according to the internal representation of lists in the > >> >> >> > programming > >> >> >> > langauge > >> >> >> > >> >> >> typo. Please enable a spell checker :) > >> >> > > >> >> > > >> >> > Ok. > >> >> > > >> >> >> > >> >> >> > >> >> >> > +implementing that part of the system. When such a list has to > be > >> >> >> > serialized > >> >> >> > +externally (such as on the RAPI interface), it will be > serialized > >> >> >> > in > >> >> >> > JSON > >> >> >> > +format. > >> >> >> > >> >> >> I think you're going into too much detail (about programming > >> >> >> languages) > >> >> >> and too little - JSON format, but what data type? I'd leave out > the > >> >> >> note > >> >> >> about the programming language, and just say what data type at > JSON > >> >> >> level, since that's the interoperation point. > >> >> > > >> >> > > >> >> > Actually, I thought about the naive transformation of a list of > >> >> > 2-tuples > >> >> > to > >> >> > JSON, that is the list of lists with two elements (that are > strings, > >> >> > as > >> >> > already specified in the descriptions of "source" and "reason"). > >> >> > That's > >> >> > why > >> >> > I didn't specify it. > >> >> > But, of course, I can add it explicitly. > >> >> > > >> >> >> > >> >> >> > >> >> >> > +Any component the operation goes through is allowed (but not > >> >> >> > required) > >> >> >> > to append > >> >> >> > +it's own reason to the list. > >> >> >> > +Other than this, the list shouldn't be modified. > >> >> >> > >> >> >> Weird formatting again (missing blank line _or_ extra hard break). > >> >> > > >> >> > > >> >> > Will fix it. Too much Latex in the last few months, I guess... > >> >> > > >> >> >> > >> >> >> > +As an example here is the reason trail for a shutdown operation > >> >> >> > invoked > >> >> >> > from > >> >> >> > +the command line through the gnt-instance tool:: > >> >> >> > + > >> >> >> > + [("user", "Cleanup of unused instances"), > ("gnt:gnt-instance", > >> >> >> > "stop"), > >> >> >> > + ("gnt:cmdlib", "LUInstanceShutdown"), > >> >> >> > + ("gnt:noded", "perspective_instance_reboot"), > >> >> >> > + ("gnt:backend", "InstanceShutdown"), ("gnt:hv_xen", > >> >> >> > "StopInstance")] > >> >> >> > >> >> >> This trail is inconsistent. Are you using module names? Entity > >> >> >> names? > >> >> > > >> >> > > >> >> > For the internal components, I used file names (without the > >> >> > extension). > >> >> > "User", on the other hand, is just an arbitrary string. It could be > >> >> > turned > >> >> > into something more formalized, by, in general, we cannot expect > >> >> > anything > >> >> > specific above this level: everything would just be user-provided. > >> >> > > >> >> > >> >> Let's try having more consistent names, also. And also avoid capital > >> >> letters and camelcasing. :) > >> > > >> > > >> > They are consistent, if you consider that they are the names of the > >> > actual > >> > functions that would create the trail. But I agree that looking at all > >> > of > >> > them from here is quite ugly and inconsistent. > >> > > >> >> > >> >> For the actor I would say > >> >> > >> >> gnt:opcode:shutdown > >> >> gnt:client:cli or gnt:client:rapi (or gnt:client:hbal, eg) > >> >> > >> >> Some of these won't have a "why" (opcodes or rpcs don't need one, the > >> >> why is usually at a higher level). > >> > > >> > > >> > Then, for example for "gnt:opcode:shutdown" isn't it better to have > just > >> > "gnt:opcode" as the actor and "shutdown" as the reason? This way the > >> > information is already much more structured, and less parsing (as > simple > >> > as > >> > it would be) is required to use it afterwards. > >> > > >> > >> Not sure. shutdown is just "which opcode are we talking about" rather > >> than the "reason". :) > > > > > > I see. Right. > > > >> > >> It seems we are just using the "last" element as reason. Which makes > >> me question whether we want the reason at all. > > > > > > Well, we could make the "reason" field optional, so the trail would > contain > > it where available, and work just as an execution trace elsewhere. > > > >> user:mtartara can shut down a cluster for chg:194564 > >> system:virgil can shut down an instance for "user-request" > >> but if it's gnt:opcode I don't see the "reason" as being shutdown. At > >> most the reason for an opcode can be a job number opcode-index. > >> (which the reason that opcode was executed) > > > > > > Is it possible to get the job number from the opcode? I remember looking > for > > a way to do it but not finding it. > > Or where can it be taken from? > > > > Not possible, indeed. But this can be fixed, and of course the job > number and opcode index can be added to the > trail before it is passed to the opcode, by jqueue/mcpu, as iustin > suggested) > > Ok, I'll have a look at jqueue/mcpu and integrate it in the design. Thanks! Michele
