.. _section-components:

Components
**********

|CONNEXT| |OBSERVABILITY| consists of three RTI components:

-  |RTI| |MONITORINGLIBRARY2| enables you to instrument a |Connext|
   application to forward telemetry data. The library also accepts
   remote commands to change the set of forwarded metrics and logs at
   runtime.

-  |RTI| |OCS| collects and aggregates telemetry data from multiple applications 
   and forwards it to backends for storage, makes it available 
   to |ADMINCONSOLE| for remote debugging, or relays it to other |OCS| 
   instances for broader distribution.

-  |RTI| |DASHBOARDS| enable you to visualize and alert based 
   on the |Connext| application metrics, as well as display |Connext| log 
   messages.
   
To support the operational monitoring use case, |OBSERVABILITY| requires 
third-party components to store and visualize telemetry data. This release 
provides native integration with Prometheus for metrics storage, Grafana Loki 
for logs storage, and Grafana for visualization. Integration with other third-party
components is also possible when using `OpenTelemetry 
<https://opentelemetry.io/>`_ and the `OpenTelemetry Collector 
<https://opentelemetry.io/docs/collector/>`_.

|DASHBOARDS| are provided as a set of Grafana 
dashboards to be deployed on a Grafana server. These dashboards only work with 
the Prometheus and Grafana Loki backends. Future releases could support other 
backends.

:numref:`FigureFramework` shows a simple representation of how
|OBSERVABILITY| components work together. 

.. figure:: static/rti_observability_framework.png
    :alt: The RTI Observability Framework 
    :name: FigureFramework
    :align: center
    :figwidth: 100%

    Observability Framework Components


.. _section-library-component:

Monitoring Library 2.0
======================

|MONITORINGLIBRARY2| includes the following key features:

- Collection and forwarding of |Connext| observables (metrics and 
  non-metric observables) and logs (including security event logs).

- Configuration using :link_connext_dds_pro_um:`MONITORING QosPolicy (DDS Extension) <#users_manual/MONITORING_QosPolicy.htm>`. 
  The QoS policy can be set programmatically or via XML.

- Runtime changes to the collection and forwarding of metrics and logs using 
  remote commands from |OCS|.

- Ability to enable and disable use of |MONITORINGLIBRARY2| at 
  runtime by changing the Monitoring QoS policy.

- Lower overhead as compared to using the 
  :link_connext_dds_pro_um:`RTI Monitoring Library<#users_manual/PartMonitoringLib.htm>`.

For more information, see :ref:`section-monitoring-library-2`.

.. _section-collector-service-component:

Collector Service
=================

|OCS| scalably collects and distributes telemetry data
forwarded by |MONITORINGLIBRARY2| in a |Connext| application. 
|COLLECTORSERVICE| is distributed as a Docker™ image. 

|OCS| includes the following key features:

- Collecting and distributing telemetry data forwarded by |Connext| applications 
  (using |MONITORINGLIBRARY2|) or other collectors.

- Sending telemetry data for storage to Prometheus for metrics and Grafana Loki 
  for logs and security events.
  
- Ability to send telemetry data to an OpenTelemetry Collector using the 
  OpenTelemetry protocol (OTLP). This feature enables integration with
  third-party observability backends other than Prometheus and Grafana Loki.

- Remote command forwarding from |DASHBOARDS| to the |Connext| applications and
  other resources to which the commands are directed. Remote commands may be used
  to control the forwarding of log messages and metrics. For detailed information
  on the commands supported see :ref:`section-collector-service-rest-api-reference`.

- Sending of observables to the :link_tools_admin_console:`RTI Admin Console <p2_administration/features_reference/ref_remote_debugging.html>` 
  for remote debugging using a WebSocket API.

For more information about the image, see `the Collector Service article <https://hub.docker.com/r/rticom/collector-service>`_ in Docker Hub.

Supported Endpoints
-------------------

|OCS| receives data by instantiating receiver endpoints, and it forwards 
data by instantiating exporter endpoints.

Currently, the only supported receiver endpoint is a DDS receiver endpoint, 
which receives telemetry data from |MONITORINGLIBRARY2| in a |Connext| 
application or from another |OCS| instance.

The following exporter endpoints are supported:

* **Prometheus exporter**, which exports metrics to a Prometheus server.
* **Grafana Loki exporter**, which exports logs to a Grafana Loki server.
* **OTLP exporter**, which exports metrics and logs to an
  OpenTelemetry Collector using the OpenTelemetry protocol (OTLP).
* **WebSocket exporter**, which provides observables to 
  :link_tools_admin_console:`RTI Admin Console <p2_administration/features_reference/ref_remote_debugging.html>` for remote debugging using
  a WebSocket API.
* **DDS exporter**, which forwards telemetry data to another |OCS| instance.

.. note:: 
    The Websocket API provided by |OCS| is not publicly available in this 
    release.

When configured with both a DDS receiver and a DDS exporter, |OCS| acts as a 
forwarder, receiving telemetry from |Connext| applications and relaying it 
to another |OCS| instance. This configuration allows for
scalable distribution of telemetry data across multiple |OCS| instances.

.. _section-built-in-configurations:

Built-in Configurations
-----------------------

The |OCS| Docker image includes a set of built-in configurations. These 
automatically set up |OCS| with a DDS receiver and various exporters, 
depending on the selected configuration.

The built-in configurations available in this release are listed in :numref:`TableDockerContainerOperationModes`.

.. list-table:: Docker Container Operation Modes
    :name: TableDockerContainerOperationModes
    :widths: 30 50 30 10
    :header-rows: 1

    * - Configuration Name
      - Supported Exporter(s)
      - Network
      - Security

    * - NonSecureForwarderLANtoLAN
      - dds_exporter
      - LAN to LAN
      - No

    * - NonSecureForwarderLANtoWAN
      - dds_exporter
      - LAN to WAN
      - No

    * - NonSecureForwarderWANtoWAN
      - dds_exporter
      - WAN to WAN
      - No

    * - SecureForwarderLANtoLAN
      - dds_exporter
      - LAN to LAN
      - Yes

    * - SecureForwarderLANtoWAN
      - dds_exporter
      - LAN to WAN
      - Yes

    * - SecureForwarderWANtoWAN
      - dds_exporter
      - WAN to WAN
      - Yes

    * - NonSecureLAN
      - prometheus_exporter, loki_exporter, websocket_exporter
      - LAN
      - No

    * - NonSecureWAN
      - prometheus_exporter, loki_exporter, websocket_exporter
      - WAN
      - No

    * - SecureLAN
      - prometheus_exporter, loki_exporter, websocket_exporter
      - LAN
      - Yes

    * - SecureWAN
      - prometheus_exporter, loki_exporter, websocket_exporter
      - WAN
      - Yes

    * - NonSecureOTelLAN
      - otlp_exporter, websocket_exporter
      - LAN
      - No

    * - NonSecureOTelWAN
      - otlp_exporter, websocket_exporter
      - WAN
      - No

    * - SecureOTelLAN
      - otlp_exporter, websocket_exporter
      - LAN
      - Yes

    * - SecureOTelWAN
      - otlp_exporter, websocket_exporter
      - WAN
      - Yes

    * - NonSecureRemoteDebuggingLAN
      - websocket_exporter
      - LAN
      - No

    * - NonSecureRemoteDebuggingWAN
      - websocket_exporter
      - WAN
      - No

    * - SecureRemoteDebuggingLAN
      - websocket_exporter
      - LAN
      - Yes

    * - SecureRemoteDebuggingWAN
      - websocket_exporter
      - WAN
      - Yes



Third-Party Components
----------------------

|OCS| includes native integration with Prometheus 
and Grafana Loki to store metrics and logs (including security events), 
respectively.

.. figure:: static/native_integration.png
    :alt: Native Integration
    :name: FigureNative
    :align: center
    :figwidth: 100%

    Native Integration

This release also allows integrating with other third-party storage 
components using OpenTelemetry and the OpenTelemetry Collector.

.. figure:: static/opentelemetry_integration.png
    :alt: OpenTelemetry Integration
    :name: FigureOpenTelemetry
    :align: center
    :figwidth: 100%

    OpenTelemetry Integration

.. _section-dashboards-component:

Observability Dashboards
========================

A set of hierarchical Grafana dashboards displays alerts when a problem
occurs and provides visualizations to help perform root cause analysis.
The dashboards get the telemetry data from a Prometheus server and
the logs from a Grafana Loki server, supporting the operational
monitoring use case.

For more information, see the :ref:`section-observability-dashboards` chapter.