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
>
> .. 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…
> +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 :)
> +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.
> +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).
> +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?
Furthermore, this shows trails from the backend, which as we discussed
in our offline meeting can't be added to the opcode.
> +where the first pair is optional and it is determined by a user-specified
> +message, passed to gnt-instance through a command line parameter.
> +
> +The same operation, launched by an external GUI tool, and executed through
> the
> +remote API, would have a reason trail like::
> +
> + [("user", "Cleanup of unused instances"), ("RemoteToolName", "GUI_stop"),
> + ("gnt:rapi_client", "ShutdownInstance"),
> + ("gnt:rlib2", "instances_name_shutdown"),
> + ("gnt:cmdlib", "LUInstanceShutdown"),
> + ("gnt:noded", "perspective_instance_reboot"),
> + ("gnt:backend", "InstanceShutdown"), ("gnt:hv_xen", "StopInstance")]
> +
> +Implementation
> +==============
> +
> +The implementation will start from the operations that affect the instance
> +status. They will be changed so that the "reason" is passed to them.
> +They will then export the new expected instance status, together
> +with the associated reason for the monitoring daemon.
> +
> +This implementation will have to be done in such a way to be extendable to
> +other opcodes if/when needed.
You left out the actual content here. How/when will this be added to
opcodes? How is hv_xen above passing back data and modifies the
(readonly) opcode?
regards,
iustin
