2.4.4. Remote Debugging

The remote debugging feature enables Admin Console to access Connext discovery-related telemetry data (builtin topics) without participating directly in the Connext application domains. Remote mode enables Admin Console to visualize telemetry data from applications running on remote systems. The data exchanged can be secured using HTTPS and BASIC authentication to make sure its confidentiality and integrity are preserved.

All Admin Console modes of operation are mutually exclusive. When working in remote mode, online and offline modes are unavailable.

Remote mode works in tandem with RTI Observability Framework using Collector Service. Observability Framework and Admin Console in remote mode can be run simultaneously to provide a robust approach for analyzing remote distributed systems. However, Observability Framework is not required to use remote debugging in Admin Console.

Note

For information about Observability Framework and Collector Service, see the Observability User’s Manual.

2.4.4.1. Before You Begin

Note

If you have installed Observability Framework, the following requirements are already met.

Remote debugging in Admin Console uses the Collector Service and Monitoring Library 2.0 components of the Observability Framework. Collector Service is distributed as a container image hosted in Docker Hub.

Using remote mode requires the following:

  • RTI license file. For instructions on how to install a license file, see Installing the License File in the RTI Connext Installation Guide.

  • Docker Engine. Install Docker Engine to build and run the Collector Service container image.

  • RTI Collector Service. After installing Docker Engine, pull the Collector Service container using the docker pull rticom/collector-service command.

Important

The Collector Service container image is only supported on x86 Linux hosts.

2.4.4.2. Configure Remote Debugging

After meeting the above requirements, configure Admin Console to use remote mode:

  • Enable Monitoring Library 2.0 to forward remote debugging data to a Collector Service instance from a Connext application. Monitoring Library 2.0 is included in the Connext Professional installation.

  • Run Collector Service to distribute remote debugging data forwarded by Monitoring Library 2.0.

2.4.4.2.1. Enabling Monitoring Library 2.0

Monitoring Library 2.0 allows you to instrument a Connext application to forward telemetry data. It must be enabled to use remote mode in Admin Console.

If you are using Observability Framework, Monitoring Library 2.0 is already enabled and configured. If you are not using Observability Framework, you need to enable Monitoring Library 2.0. Use the MONITORING QosPolicy (DDS Extension) on the DomainParticipantFactory and set participant_factory_qos.monitoring.enable to true. For example:

<qos_library name="MyQosLibrary">
    <qos_profile name="MyApplicationProfile" is_default_participant_factory_profile="true">
        <participant_factory_qos>
            <!-- Enable monitoring -->
            <monitoring>
                <enable>true</enable>
            </monitoring>
        </participant_factory_qos>
    </qos_profile>
</qos_library>

For detailed information and examples, see Monitoring Library 2.0 in the RTI Connext Observability Framework User’s Manual.

2.4.4.2.2. Running Collector Service

Collector Service collects telemetry data forwarded by Monitoring Library 2.0. The Collector Service instance collecting remote debugging data must use a WebSocket exporter endpoint. For more information, see Collector Service in the Connext Observability Framework User’s Manual.

Collector Service can run in two security configurations:

  • Secure. Data is secured using BASIC-Auth over HTTPS.

  • Non-secure. Data is not secured; anyone with the server URL can connect to the remote system.

2.4.4.2.2.1. Secure

Collector Service uses two HTTP servers; one to receive remote commands and another one to expose the metrics. The communication with these HTTP servers is secured using HTTPS and BASIC authentication. You must provide the security artifacts required to configure the HTTP servers running in Collector Service.

There are two built-in configurations in Collector Service for secure remote debugging:

  • SecureRemoteDebuggingWAN: Connect to remote systems over WAN using HTTPS and BASIC authentication.

  • SecureRemoteDebuggingLAN: Connect to remote systems over LAN using HTTPS and BASIC authentication.

To run Collector Service securely, follow these steps:

  1. Generate the server.pem and htdigest security files. For details, see Generating HTTPS Security Artifacts in the RTI Connext Observability Framework User’s Manual.

  2. Run the following command to start Collector Service. This example uses the SecureRemoteDebuggingWAN configuration; change the CFG_NAME environment variable as needed.

    docker run -dt \
        --network host \
        -v [path to server.pem]/Server.pem:/rti/security/https/serverControl.pem \
        -v [path to htdigest]/htdigest:/rti/security/https/htdigest_control \
        -v [path to license file]/rti_license.dat:/opt/rti.com/rti_connext_dds-7.6.0/rti_license.dat \
        -e OBSERVABILITY_CONTROL_PUBLIC_HOSTNAME="<public hostname>" \
        -e OBSERVABILITY_HOSTNAME="<hostname>" \
        -e OBSERVABILITY_CONTROL_PORT="19098s" \
        -e OBSERVABILITY_CONTROL_PUBLIC_PORT="19098s" \
        -e CFG_NAME="SecureRemoteDebuggingWAN" \
        --name=collector_service \
        rticom/collector-service:[label]

2.4.4.2.2.2. Non-secure

There are two built-in configurations in Collector Service for non-secure remote debugging:

  • NonSecureRemoteDebuggingWAN: Connect to remote systems without security over WAN.

  • NonSecureRemoteDebuggingLAN: Connect to remote systems without security over LAN.

To run Collector Service without security:

docker run -dt \
    --network host \
    -v [path to license file]/rti_license.dat:/opt/rti.com/rti_connext_dds-7.6.0/rti_license.dat \
    -e OBSERVABILITY_CONTROL_PUBLIC_HOSTNAME="<public hostname>" \
    -e OBSERVABILITY_HOSTNAME="<hostname>" \
    -e OBSERVABILITY_CONTROL_PORT="19098" \
    -e OBSERVABILITY_CONTROL_PUBLIC_PORT="19098" \
    -e CFG_NAME="NonSecureRemoteDebuggingLAN" \
    --name=collector_service \
    rticom/collector-service:[label]

2.4.4.3. Enable Remote Debugging in Admin Console

To enable remote mode, go to View > Preferences > Administration, then select the Remote tab.

RemoteMode2

  • Server URL: Enter the protocol, address, port, and the Collector Service path for the remote system. The default port and Collector Service path are included; change the default url as needed.

    • When using a non-secure WebSockets connection, use the format ws://<ip>:<port>/rti/collector_service/v1/observables.

    • When using a secure WebSockets connection, use the format wss://<ip>:<port>/rti/collector_service/v1/observables.

  • Basic auth: If using a secure connection, select Basic auth and enter your credentials.

To establish the connection, select Connect. If the connection is successful, the Current status area displays the connection information. If the connection fails, the following error message displays.

RemoteModeConnectionFailed

To end the active remote session, select Disconnect.

RemoteModeDisconnect

Remote mode provides the ability to use all of the existing Admin Console features that rely solely on discovery information. These features include:

  • DDS Logical View: A hierarchical view of the remote system’s domains and Topics.

  • Physical View: A hierarchical view of the hosts and processes running in the system.

  • Processes View: A tabular view of all system processes.

  • Health View: A tabular view displaying the health of a selected system Entity.

  • Match Analyses View: A hierarchical view of one or more match analyses for a selected Entity.

  • DDS Data Type View: A hierarchical or IDL text view of the data types used by a selected DataWriter or DataReader.

  • DDS QoS View: A hierarchical view of QoS settings for a selected Entity.

  • System View: A graphical representation of the remote system.

  • Host View: A tabular view summarizing general information about the remote hosts.

  • Process View: Multiple panels that provide details about each process’s DDS Entities.

  • Topic View: Multiple tabs that provide details about a selected Topic.

2.4.4.3.1. Limitations

The Admin Console features that require subscribing to or publishing Topics are not available in remote mode. As a result, the following Topic View tabs are inaccessible when monitoring remote systems:

Additionally, RTI Connext Infrastructure Services and RTI Distributed Logger are not supported in remote mode.

Note

Remote Debugging is not backwards compatible. This feature is available only in Connext 7.5.0 and higher.