Introspection

See also

Introspect

Introspection tool

Overview

The introspection protocol allows discovering participants, processes and hosts participating in a running RSB system, including some information about their respective states and properties. The “meta-communication” of the introspection protocol is implemented using the same transports and events as “ordinary” participants (i.e. there are no special-purpose communication channels for introspection).

RSB implementations as well as individual participants are encouraged but not required to support this introspection protocol.

The introspection communication pattern consists of two roles:

LocalIntrospection

Objects of this kind collect information about

  • 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 introspection protocol to query LocalIntrospection objects collecting information about all (introspectable) participants, processes and hosts in an entire system.

Note

participants that are part of the implementation of the introspection mechanism should not support introspection themselves. Otherwise infinite chains of meta-participants would arise.

Participant Introspection

The participant introspection protocol uses the following (reserved) scopes:

scope /__rsb/introspection/participants/

This scope is used in introspection surveys addressing all participants.

scope /__rsb/introspection/participants/ID

where ID is the string representation (of the form 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 participant. These scopes are used for requesting and sending information about individual participants.

Introspection Broadcasts

  1. When a participant with unique id ID is created, an event is sent to the scope /__rsb/introspection/participants/ID

    • The payload is an rsb.protocol.introspection.Hello object:

      message definitions are hidden

        1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
      /* ============================================================
 *
 * This file is part of the RSB project.
 *
 * Copyright (C) 2014 The RSB developers.
 *
 * This file may be licensed under the terms of the
 * GNU Lesser General Public License Version 3 (the ``LGPL''),
 * or (at your option) any later version.
 *
 * Software distributed under the License is distributed
 * on an ``AS IS'' basis, WITHOUT WARRANTY OF ANY KIND, either
 * express or implied. See the LGPL for the specific language
 * governing rights and limitations.
 *
 * You should have received a copy of the LGPL along with this
 * program. If not, go to http://www.gnu.org/licenses/lgpl.html
 * or write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 * The development of this software was supported by:
 *   CoR-Lab, Research Institute for Cognition and Robotics
 *     Bielefeld University
 *
 * ============================================================ */

syntax = "proto2";

package rsb.protocol.introspection;

import "rsb/protocol/operatingsystem/Process.proto";
import "rsb/protocol/operatingsystem/Host.proto";

option java_outer_classname = "HelloType";

/**
 * Basic introspection information for one RSB participant.
 *
 * May describe a newly created or an already existing participant.
 *
 * @author Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
 */
message Hello {

    // Participant Information

    /**
     * Kind of the participant as lowercase string.
     *
     * Examples: "informer", "listener", "reader", etc.
     */
    required string                                kind      = 1;

    /**
     * ID (a RFC 4122 UUID) of the participant as byte array.
     *
     * For this encoding, the encoded UUID is 16 bytes long.
     */
    // @constraint(len(value) = 16)
    required bytes                                 id        = 2;

    /**
     * If present, ID (a RFC 4122 UUID) of the composite participant
     * containing the participant as a byte array.
     *
     * If not present, the participant is not contained in a composite
     * participant (it may still be a composite participant and itself
     * contain other participants, though)
     *
     * For this encoding, the encoded UUID is 16 bytes long.
     */
    // @constraint(len(value) = 16)
    optional bytes                                 parent    = 3;

    /**
     * Scope on which the participant listens, publishes or otherwise
     * operates.
     *
     * @todo proper representation
     */
    required string                                scope     = 4;

    /**
     * Type of data produced or consumed by the participant.
     *
     * Programming language data-type within the containing program
     * for now. For visual inspection only - Do not process.
     *
     * @todo Preliminary: will change to a proper representation
     */
    optional string                                type      = 5;

    /**
     * A list of strings describing transports of the participant.
     *
     * @todo Preliminary: will change.
     */
    repeated string                                transport = 6;

    // Process Information

    /**
     * Information about the process containing the participant.
     */
    required .rsb.protocol.operatingsystem.Process process   = 7;

    // Host Information

    /**
     * Host on which the containing process executes.
     */
    required .rsb.protocol.operatingsystem.Host    host      = 8;

}

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
      /* ============================================================
 *
 * This file is part of the RSB project.
 *
 * Copyright (C) 2014 The RSB developers.
 *
 * This file may be licensed under the terms of the
 * GNU Lesser General Public License Version 3 (the ``LGPL''),
 * or (at your option) any later version.
 *
 * Software distributed under the License is distributed
 * on an ``AS IS'' basis, WITHOUT WARRANTY OF ANY KIND, either
 * express or implied. See the LGPL for the specific language
 * governing rights and limitations.
 *
 * You should have received a copy of the LGPL along with this
 * program. If not, go to http://www.gnu.org/licenses/lgpl.html
 * or write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 * The development of this software was supported by:
 *   CoR-Lab, Research Institute for Cognition and Robotics
 *     Bielefeld University
 *
 * ============================================================ */

syntax = "proto2";

package rsb.protocol.operatingsystem;

option java_outer_classname = "ProcessType";

/**
 * Basic information about an operatingsystem process.
 *
 * @author Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
 */
message Process {

    /**
     * Should uniquely identify the process on one machine.
     *
     * On POSIX systems, a string representation of the PID is used.
     */
    required string id                    = 1;

    /**
     * Name of the program executed by the process.
     *
     * Should not include the full path of the program. TODO or should it?
     *
     * On POSIX systems, argv[0].
     */
    required string program_name          = 2;

    /**
     * List of commandline arguments with which the process has been
     * started.
     *
     * On POSIX systems, does not include argv[0], i.e. argv[1:].
     */
    repeated string commandline_arguments = 3;

    /**
     * Start time of the process encoded as a timestamp in UTC in
     * microseconds since UNIX epoch.
     *
     * http://docs.cor-lab.org/rsb-manual/trunk/html/specification-event.html#timestamps
     */
    required uint64 start_time            = 4;

    /**
     * Login- or account-name of the user executing the process.
     *
     * Can be omitted when not known, for example because of security
     * policy constraints.
     */
    optional string executing_user        = 5;

    /**
     * The version of the RSB implementation used in this process.
     *
     * The version string is of the form
     *
     *   MAJOR.MINOR.REVISION[-COMMIT]
     */
    optional string rsb_version           = 7;

    /**
     * A user-defined name for the process.
     */
    optional string display_name          = 8;

}

        1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
      /* ============================================================
 *
 * This file is part of the RSB project.
 *
 * Copyright (C) 2014 The RSB developers.
 *
 * This file may be licensed under the terms of the
 * GNU Lesser General Public License Version 3 (the ``LGPL''),
 * or (at your option) any later version.
 *
 * Software distributed under the License is distributed
 * on an ``AS IS'' basis, WITHOUT WARRANTY OF ANY KIND, either
 * express or implied. See the LGPL for the specific language
 * governing rights and limitations.
 *
 * You should have received a copy of the LGPL along with this
 * program. If not, go to http://www.gnu.org/licenses/lgpl.html
 * or write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 * The development of this software was supported by:
 *   CoR-Lab, Research Institute for Cognition and Robotics
 *     Bielefeld University
 *
 * ============================================================ */

syntax = "proto2";

package rsb.protocol.operatingsystem;

option java_outer_classname = "HostType";

/**
 * Basic description of a host.
 *
 * @author Jan Moringen <jmoringe@techfak.uni-bielefeld.de>
 */
message Host {

    /**
     * Arbitrary string (hopefully) uniquely identifying the host.
     *
     * The following sources should be used for determining this
     * string (in order of preference for each platform):
     *
     * Linux
     *
     *   * contents of /etc/machine-id (excluding whitespace characters)
     *   * contents of /var/lib/dbus/machine-id (excluding whitespace
     *     characters)
     *   * As a last resort, the value may be omitted in which case
     *     the hostname will be used as a means of identifying the
     *     host.
     *
     * Windows
     *
     *   Since the appropriate C API function (GetComputerObjectName)
     *   is difficult to use in some languages, the hostname should be
     *   used instead.
     *
     * MacOS
     *
     *   Since the appropriate C API function (gethostuuid) is
     *   difficult to use in some languages, the hostname should be
     *   used instead.
     *
     * Other operating systems
     *
     *   A unique id provided by the operating should be used when it
     *   can easily be used from all languages (i.e. readable from
     *   file), otherwise the hostname should be used.
     */
    required string id               = 1;

    /**
     * Human-readable name of the host.
     */
    required string hostname         = 2;

    /**
     * Type of the machine, usually CPU architecture.
     *
     * The value is a lower-case string that identifies the processor
     * family and potentially associated system architecture,
     * generally without indicating a specific vendor or version.
     *
     * For 32-bit and 64-bit CPUs in the x86 family, the values "x86"
     * and "x86_64" should be used.
     */
    optional string machine_type     = 3;

    /**
     * Version of the machine within its type, usually CPU
     * identification string.
     *
     * On Linux, the value of the "model name" field in the
     * "/proc/cpuinfo" file can be used.
     */
    optional string machine_version  = 4;

    /**
     * Type of the operating system running on the machine, usually
     * the kernel name.
     *
     * The value is a lower-case string that identifies the operating
     * system running on the machine without indicating a specific
     * version of that operating system.
     *
     * For Linux, MacOS and Windows the strings "linux", "darwin" and
     * "win32" should be used respectively.
     */
    optional string software_type    = 5;

    /**
     * Version of the operating system within its type, usually the
     * kernel version string.
     *
     * On Linux and MacOS, the output of the command "uname -r".
     */
    optional string software_version = 6;

}

      As described in the documentation of the message definitions, the payload contains information regarding the participant, its process and host.

      It should be noted that the host id and process id contained in the payload can be used to construct the scope under which the process can be introspected (See Process and Host Introspection).

    • The method field is empty

    • The causal vector is empty

  2. When a participant with unique id ID is destroyed, an event is sent to the scope /__rsb/introspection/participants/ID

    • The payload is an rsb.protocol.introspection.Bye object:

      message definition is hidden

       1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
      /* ============================================================
 *
 * This file is part of the RSB project.
 *
 * Copyright (C) 2014 The RSB developers.
 *
 * This file may be licensed under the terms of the
 * GNU Lesser General Public License Version 3 (the ``LGPL''),
 * or (at your option) any later version.
 *
 * Software distributed under the License is distributed
 * on an ``AS IS'' basis, WITHOUT WARRANTY OF ANY KIND, either
 * express or implied. See the LGPL for the specific language
 * governing rights and limitations.
 *
 * You should have received a copy of the LGPL along with this
 * program. If not, go to http://www.gnu.org/licenses/lgpl.html
 * or write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 * The development of this software was supported by:
 *   CoR-Lab, Research Institute for Cognition and Robotics
 *     Bielefeld University
 *
 * ============================================================ */

syntax = "proto2";

package rsb.protocol.introspection;

option java_outer_classname = "ByeType";

/**
 * Indicates removal of a particular participant from the bus.
 *
 * @author Jan Moringen <jmoringe@techfak.uni-bielfeld.de>
 */
message Bye {

    /**
     * ID (a RFC 4122 UUID) of the participant as byte array.
     *
     * For this encoding, the encoded UUID is 16 bytes long.
     */
    // @constraint(len(value) = 16)
    required bytes id = 1;

}

      As described in the documentation of the message definition, the only information contained in the payload is the unique id of the participant.

    • The method field is empty

    • The causal vector is empty

Introspection Surveys

  1. The client (a RemoteIntrospection object) sends an event to the scope /__rsb/introspection/participants/

  2. All LocalIntrospection objects receiving the event, for each known participant for which introspection is enabled, send an event on the scope /__rsb/introspection/participants/ID where ID is the string representation of the unique id of the respective participant as explained above.

Note

The only difference between introspection broadcasts and responses to introspection surveys is the contents of the causal vector. Processors of introspection broadcasts and responses (e.g. RemoteIntrospection objects) may choose to ignore this difference and process all such events in the same way.

Process and Host Introspection

The process and host introspection protocol uses the following (reserved) scopes:

scope /__rsb/introspection/hosts/HOST-ID/PROCESS-ID

where HOST-ID is the unique id of the host on which the current process is executed and PROCESS-ID is its unique id within the host. See the documentation of the rsb.protocol.operatingsystem.Host message for construction of HOST-ID.

Examples:

  • /__rsb/introspection/hosts/6116ead66a78e7d2970e5380479796df/1884/

  • /__rsb/introspection/hosts/ferberit/42/

Each process that supports RSB introspection operates a remote server on this scope iff there is at least one active participant in the process. This remote server provides the following methods:

echo()

Send any received event back to the caller with the following timestamps added:

Note

The introspection mechanism cannot directly discover hosts and processes. Instead, the first participant of a process that is announced via an event containing a rsb.protocol.introspection.Hello 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++

“1.0” branch of https://github.com/open-rsx/rsb-cpp at src/rsb/introspection/

Java

not implemented yet

Python

upstream/rsb-python/rsb/introspection/__init__.py

Common Lisp

“1.0” branch of https://github.com/open-rsx/rsb-cl at src/introspection/