.. _specification-introspection: =============== Introspection =============== .. seealso:: :ref:`tool-introspect` :term:`Introspection` tool Overview ======== The :term:`introspection` protocol allows discovering :term:`participants `, processes and hosts participating in a running |project| system, including some information about their respective states and properties. The "meta-communication" of the :term:`introspection` protocol is implemented using the same :term:`transports ` and :term:`events ` as "ordinary" :term:`participants ` (i.e. there are no special-purpose communication channels for :term:`introspection`). |project| implementations as well as individual :term:`participants ` are encouraged but not required to support this :term:`introspection` protocol. The :term:`introspection` communication pattern consists of two roles: ``LocalIntrospection`` Objects of this kind collect information about * :term:`participants ` in a single process * the process itself * and the host on which the process is executed and make it available for ``RemoteIntrospection`` objects. ``RemoteIntrospection`` Objects of this kind use the :term:`introspection` protocol to query ``LocalIntrospection`` objects collecting information about all (introspectable) :term:`participants `, processes and hosts in an entire system. .. note:: :term:`participants ` that are part of the *implementation* of the :term:`introspection` mechanism should not support :term:`introspection` themselves. Otherwise infinite chains of meta-:term:`participants ` would arise. .. _introspection-participants: Participant Introspection ========================= The :term:`participant` :term:`introspection` protocol uses the following (:ref:`reserved `) :term:`scopes `: :term:`scope` ``/__rsb/introspection/participants/`` This :term:`scope` is used in :term:`introspection` surveys addressing all :term:`participants `. :term:`scope` :samp:`/__rsb/introspection/participants/{ID}` where :samp:`{ID}` is the string representation (of the form :samp:`{GROUP1}-{GROUP2}-{GROUP3}-{GROUP4}-{GROUP5}`, as specified in :rfc:`4122`, for example ``/__rsb/introspection/participants/AC259445-0EE4-4164-A5A5-EB08EC5B325D/``) of the unique id of a :term:`participant`. These :term:`scopes ` are used for requesting and sending information about individual :term:`participants `. .. _introspection-participants-broadcasts: Introspection Broadcasts ------------------------ #. When a :term:`participant` with unique id :samp:`{ID}` is created, an :term:`event` is sent to the :term:`scope` :samp:`/__rsb/introspection/participants/{ID}` * The :term:`payload` is an :py:class:`rsb.protocol.introspection.Hello` object: .. container:: message-hello-multi .. container:: message-hello-hide *message definitions are hidden* .. container:: message-hello-show .. literalinclude:: ../rsb-protocol/proto/rsb/protocol/introspection/Hello.proto :language: protobuf :linenos: .. literalinclude:: ../rsb-protocol/proto/rsb/protocol/operatingsystem/Process.proto :language: protobuf :linenos: .. literalinclude:: ../rsb-protocol/proto/rsb/protocol/operatingsystem/Host.proto :language: protobuf :linenos: As described in the documentation of the message definitions, the :term:`payload` contains information regarding the :term:`participant`, its process and host. It should be noted that the host id and process id contained in the :term:`payload` can be used to construct the :term:`scope` under which the process can be :term:`introspected ` (See :ref:`introspection-processes-and-hosts`). * The :term:`method field` is empty * The :term:`causal vector` is empty #. When a :term:`participant` with unique id :samp:`{ID}` is destroyed, an :term:`event` is sent to the :term:`scope` :samp:`/__rsb/introspection/participants/{ID}` * The :term:`payload` is an :py:class:`rsb.protocol.introspection.Bye` object: .. container:: message-bye-multi .. container:: message-bye-hide *message definition is hidden* .. container:: message-bye-show .. literalinclude:: ../rsb-protocol/proto/rsb/protocol/introspection/Bye.proto :language: protobuf :linenos: As described in the documentation of the message definition, the only information contained in the :term:`payload` is the unique id of the :term:`participant`. * The :term:`method field` is empty * The :term:`causal vector` is empty .. _introspection-participants-surveys: Introspection Surveys --------------------- #. The client (a ``RemoteIntrospection`` object) sends an :term:`event` to the :term:`scope` ``/__rsb/introspection/participants/`` * The :term:`method field` has the value ``SURVEY`` * The :term:`payload` is empty #. All ``LocalIntrospection`` objects receiving the :term:`event`, for each known :term:`participant` for which :term:`introspection` is enabled, send an :term:`event` on the :term:`scope` :samp:`/__rsb/introspection/participants/{ID}` where :samp:`{ID}` is the string representation of the unique id of the respective :term:`participant` as explained above. * The :term:`payload` is a :py:class:`rsb.protocol.introspection.Hello` object as explained in :ref:`introspection-participants-broadcasts` * The :term:`method field` is empty * The :term:`event id` of the request :term:`event` is stored in the :term:`causal vector` .. note:: The only difference between :term:`introspection` broadcasts and responses to :term:`introspection` surveys is the contents of the :term:`causal vector`. Processors of :term:`introspection` broadcasts and responses (e.g. ``RemoteIntrospection`` objects) may choose to ignore this difference and process all such :term:`events ` in the same way. .. _introspection-processes-and-hosts: Process and Host Introspection ============================== The process and host :term:`introspection` protocol uses the following (:ref:`reserved `) :term:`scopes `: :term:`scope` :samp:`/__rsb/introspection/hosts/{HOST-ID}/{PROCESS-ID}` where :samp:`{HOST-ID}` is the unique id of the host on which the current process is executed and :samp:`{PROCESS-ID}` is its unique id within the host. See the documentation of the :py:class:`rsb.protocol.operatingsystem.Host` message for construction of :samp:`{HOST-ID}`. Examples: * ``/__rsb/introspection/hosts/6116ead66a78e7d2970e5380479796df/1884/`` * ``/__rsb/introspection/hosts/ferberit/42/`` Each process that supports |project| :term:`introspection` operates a :term:`remote server` on this :term:`scope` iff there is at least one active :term:`participant` in the process. This :term:`remote server` provides the following methods: .. js:function:: echo Send any received :term:`event` back to the caller with the following :ref:`timestamps ` added: * ``request.send`` is set to the ``send`` :ref:`timestamp ` of the request :term:`event` * ``request.receive`` is set to the ``receive`` :ref:`timestamp ` of the request :term:`event` .. note:: The :term:`introspection` mechanism cannot directly discover hosts and processes. Instead, the first :term:`participant` of a process that is announced via an :term:`event` containing a :py:class:`rsb.protocol.introspection.Hello` :term:`payload` indicates the existence of its process (and potentially the host on which the process is executed). ``RemoteIntrospection`` objects call the above method periodically to determine whether a remote process is still running, detect crashes and estimate offsets between the local clock and remote clocks. Implementations =============== =========== ======================================================== Language File(s) =========== ======================================================== C++ |repository_versioned_cpp| at ``src/rsb/introspection/`` Java *not implemented yet* Python :download:`/../rsb-python/rsb/introspection/__init__.py` Common Lisp |repository_versioned_cl| at ``src/introspection/`` =========== ========================================================