.. _section-collector-service-rest-api-reference:

Collector Service REST API Reference
====================================

|OCS| scalably distributes telemetry data forwarded by |MONITORINGLIBRARY2|
in a |Connext| application and sends it to configurable backends. A 
key feature of |OCS| is remote command forwarding to the |Connext| 
applications. These commands enable you to control the amount of telemetry 
data forwarded by |MONITORINGLIBRARY2| from a |Connext| application.

This REST API reference describes the remote commands provided by |OCS|. These
commands enable you to:

 - get the current logging collection and forwarding verbosity levels for applications
 - dynamically change the logging collection and forwarding verbosity levels for applications
 - get the current metric collection configuration for observable resources
 - dynamically configure the set of metrics collected and forwarded for observable resources

Definitions
-----------

The REST API commands in the following sections share the following common 
fields:

**application**

  - The **application** field is a Uniform Resource Identifier (URI) that 
    identifies an application in responses to commands that get logging 
    verbosity levels. For details on this Uniform Resource Identifier (URI) 
    see the Application row in :numref:`TableResourceNames`.

**application_selector**

  - The **application_selector** field is a resource selector that identifies 
    one or more applications in commands that set logging verbosity levels. 
    For details on specifying a resource selector for **application_selector** 
    see :ref:`section-observable-resource-patterns`.

**resource_selector**

  - The **resource_selector** field is a resource selector that identifies one
    or more observable resources in a command. For details on specifying a
    **resource_selector** see :ref:`section-observable-resource-patterns`.

**logging_settings**

  - The **logging_settings** field is a list of objects that specify the 
    logging level for different facilities within an application. Each object 
    in the list has two properties:

    - **verbosity** levels can be ``SILENT``, ``DEBUG``, ``INFORMATIONAL``, ``NOTICE``, ``WARNING``, ``ERROR``, ``CRITICAL``, ``ALERT``, ``EMERGENCY``.
    - **facility** can be ``MIDDLEWARE``, ``SERVICE``, ``SECURITY_EVENT`` or ``USER``.

    Note that all **verbosity** levels may not be supported in the 
    |DASHBOARDS|. See :ref:`section-telemetry-logs` for details on
    logging in |OBSERVABILITY|.

**metrics**

  - The **metrics** field is a list of metric names in responses to commands
    that get metric subscription state. For details on metric names, see 
    :ref:`section-telemetry-metrics`.

**subscribe_metrics_selector**

  - The **subscribe_metrics_selector** is a list of metric names to subscribe to.
    For details on how to specify metric selectors in a **subscribe_metrics_selector**
    list, see :ref:`section-observable-metric-patterns`.

**unsubscribe_metrics_selector**

  - The **unsubscribe_metrics_selector** field is a list of metric names to
    unsubscribe to. For details on how to specify metric selectors in a 
    **unsubscribe_metrics_selector** list, see :ref:`section-observable-metric-patterns`.

Root endpoint (base URL)
------------------------

The root endpoint for the |OCS| REST API is the URL of the |OCS|. It
is the base URL for all the commands in this reference. For example: 
``https://collector_service:19080``.

The hostname and port number of the |OCS| service can be configured as 
follows:

* For an :ref:`section-evaluation-deployment`, 
  the |OCS| Host and Port information can be configured using 
  the following parameters in the configuration JSON file 
  (see :ref:`section-configure-json-file`).

   * collectorConfig.controlPublicHostname
   * collectorConfig.controlPublicPort

* For :ref:`section-production-deployment` where |OCS| is deployed as a 
  standalone Docker container, the Host and Port information can be configured 
  via two environment variables in the |OCS| Docker image
  (see the `Collector Service article <https://hub.docker.com/r/rticom/collector-service>`_
  in Docker Hub).

   * OBSERVABILITY_CONTROL_PUBLIC_HOSTNAME
   * OBSERVABILITY_CONTROL_PUBLIC_PORT

In addition, the root endpoint for the |OCS| REST API is also part of the 
label ``controllability_url``, which is associated with each 
application's presence metric 
(see :ref:`section-observable-metric-application`).

This is useful when you have multiple |OCS| instances storing data 
into a metrics backend (for example, Prometheus), and you want to 
dynamically discover the |OCS| instance that is managing a particular 
application to send remote commands to it.

API Overview
------------
.. qrefflask:: rest_api:app
  :order: path
  :undoc-static:

API Reference
-------------
.. autoflask:: rest_api:app
  :order: path
  :undoc-static: