specification-introspection.rst

Introspection

.. seealso::

   :ref:`tool-introspect`
     :term:`Introspection` tool

Overview

The :term:`introspection` protocol allows discovering :term:`participants <participant>`, 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 <transport>` and :term:`events <event>` as "ordinary" :term:`participants <participant>` (i.e. there are no special-purpose communication channels for :term:`introspection`).

|project| implementations as well as individual :term:`participants <participant>` 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 <participant>` 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 <participant>`, processes and hosts in an entire system.

Note

:term:`participants <participant>` that are part of the implementation of the :term:`introspection` mechanism should not support :term:`introspection` themselves. Otherwise infinite chains of meta-:term:`participants <participant>` would arise.

Participant Introspection

The :term:`participant` :term:`introspection` protocol uses the following (:ref:`reserved <specification-scope-reserved>`) :term:`scopes <scope>`:

:term:`scope` /__rsb/introspection/participants/

This :term:`scope` is used in :term:`introspection` surveys addressing all :term:`participants <participant>`.

: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 <scope>` are used for requesting and sending information about individual :term:`participants <participant>`.

Introspection Broadcasts

1. 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:

     message definitions are hidden

     .. literalinclude:: upstream/rsb-protocol/proto/rsb/protocol/introspection/Hello.proto
       :language: protobuf
       :linenos:
     
     

     .. literalinclude:: upstream/rsb-protocol/proto/rsb/protocol/operatingsystem/Process.proto
       :language: protobuf
       :linenos:
     
     

     .. literalinclude:: upstream/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 <introspection>` (See :ref:`introspection-processes-and-hosts`).

   • The :term:`method field` is empty

   • The :term:`causal vector` is empty

2. 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:

     message definition is hidden

     .. literalinclude:: upstream/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 Surveys

1. 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
2. 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 <event>` in the same way.

Process and Host Introspection

The process and host :term:`introspection` protocol uses the following (:ref:`reserved <specification-scope-reserved>`) :term:`scopes <scope>`:

: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 <specification-event-timestamps>` added:

   * ``request.send`` is set to the ``send`` :ref:`timestamp
     <specification-event-timestamps>` of the request :term:`event`

   * ``request.receive`` is set to the ``receive`` :ref:`timestamp
     <specification-event-timestamps>` 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:`upstream/rsb-python/rsb/introspection/__init__.py`
Common Lisp	|repository_versioned_cl| at src/introspection/