9. Collector Service REST API Reference

Observability Collector Service scalably distributes telemetry data forwarded by Monitoring Library 2.0 in a Connext application and sends it to configurable backends. A key feature of Observability Collector Service is remote command forwarding to the Connext applications. These commands enable you to control the amount of telemetry data forwarded by Monitoring Library 2.0 from a Connext application.

This REST API reference describes the remote commands provided by Observability Collector Service. 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

9.1. 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 Table 7.1.

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 Resource Pattern Definitions.

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 Resource Pattern Definitions.

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 Observability Dashboards. See Logs for details on logging in Observability Framework.

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 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 Metric Pattern Definitions.

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 Metric Pattern Definitions.

9.2. Root endpoint (base URL)

The root endpoint for the Observability Collector Service REST API is the URL of the Observability Collector Service. 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 Observability Collector Service service can be configured as follows:

  • For pre-packaged installations (see Docker Compose (Prepackaged)), the Host and Port information of the Collector Service can be configured using the following parameters in the configuration JSON file (see Configure the JSON File):

    • collectorConfig.controlPublicHostname

    • collectorConfig.controlPublicPort

  • For standalone deployments of Collector Service (see Docker (Separate Deployment)), the Host and Port information can be configured using two environment variables in the Collector Service Docker image (see the Docker Collector Service Repository):

    • OBSERVABILITY_CONTROL_PUBLIC_HOSTNAME

    • OBSERVABILITY_CONTROL_PUBLIC_PORT

In addition, the root endpoint for the Observability Collector Service REST API is also part of the label controllability_url, which is associated with each application’s presence metric (see Application Metrics).

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

9.3. API Overview

Resource

Operation

Description

logging

GET /rti/collector_service/rest1/logging:get_collection_level

Get the collection logging level.

GET /rti/collector_service/rest1/logging:get_forwarding_level

Get the forwarding logging level.

POST /rti/collector_service/rest1/logging:set_collection_level

Set the collection logging level.

POST /rti/collector_service/rest1/logging:set_forwarding_level

Set the forwarding logging level.

metrics

GET /rti/collector_service/rest1/metrics:get_subscription_state

Get the metrics subscription state.

POST /rti/collector_service/rest1/metrics:set_subscription_state

Set the metrics subscription state.

POST /rti/collector_service/rest1/metrics:update_subscription_state

Update the metrics subscription state.

9.4. API Reference

GET /rti/collector_service/rest1/logging:get_collection_level

This method gets the collection verbosity level of a given application_selector.

Request Headers:

  • Authorization – The authorization header is used to authenticate the user. The value of the header is the user’s credentials encoded in base64. The format is “Basic <base64 encoded username:password>”.

Query Parameters:

  • application_selector –

    • Description: The application_selector to get the collection verbosity level.

    • Type: string

    • Required: true

    • Example: //app_*

      GET http://.../rti/collector_service/rest1/logging:get_collection_level?application_selector=//app_* HTTP/1.1

Response Headers:
Status Codes:

  • 200 OK –

    • Description: If successful, this method returns the collection verbosity level for the applications that matched the application_selector.

    • Example Response Body:

      • application/dds-web+json

         1[
 2    {
 3        "application": "/applications/app_1",
 4        "logging_settings": [
 5            {
 6                "verbosity": "WARNING",
 7                "facility": "MIDDLEWARE"
 8            },
 9            {
10                "verbosity": "ERROR",
11                "facility": "SERVICE"
12            }
13        ]
14    },
15    {
16        "application": "/applications/app_2",
17        "logging_settings": [
18            {
19                "verbosity": "WARNING",
20                "facility": "MIDDLEWARE"
21            },
22            {
23                "verbosity": "ERROR",
24                "facility": "SERVICE"
25            }
26        ]
27    }
28]

  • 400 Bad Request –

    • Description: In case of an invalid input, this method returns a response body with the error code and a message.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 404 Not Found –

    • Description: The application is not found or does not match any application.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 500 Internal Server Error –

    • Description: Generic server error.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

GET /rti/collector_service/rest1/logging:get_forwarding_level

This method gets the forwarding verbosity level of a given application_selector.

Request Headers:

  • Authorization – The authorization header is used to authenticate the user. The value of the header is the user’s credentials encoded in base64. The format is “Basic <base64 encoded username:password>”.

Query Parameters:

  • application_selector –

    • Description: The application_selector to get the forwarding verbosity level.

    • Type: string

    • Required: true

    • Example: app_1

      GET http://.../rti/collector_service/rest1/logging:get_forwarding_level?application_selector=app_1 HTTP/1.1

Response Headers:
Status Codes:

  • 200 OK –

    • Description: If successful, this method returns the forwarding verbosity level for the applications that matched the application_selector.

    • Example Response Body:

      • application/dds-web+json

         1[
 2    {
 3        "application": "/applications/app_1",
 4        "logging_settings": [
 5            {
 6                "verbosity": "WARNING",
 7                "facility": "MIDDLEWARE"
 8            },
 9            {
10                "verbosity": "ERROR",
11                "facility": "SERVICE"
12            }
13        ]
14    }
15]

  • 400 Bad Request –

    • Description: In case of an invalid input, this method returns a response body with the error code and a message.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 404 Not Found –

    • Description: The application_selector is not found or does not match any application.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 500 Internal Server Error –

    • Description: Generic server error.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

POST /rti/collector_service/rest1/logging:set_collection_level

This method sets the collection logging level of a given application_selector.

Request Headers:

  • Content-Length – Transfer-length of the message-body.

  • Content-Type – Valid values: application/json, application/dds-web+json.

  • Authorization – The authorization header is used to authenticate the user. The value of the header is the user’s credentials encoded in base64. The format is “Basic <base64 encoded username:password>”.

Example Request Body:

  • application/dds-web+json

     1[
 2    {
 3        "application_selector": "//app_1", 
 4        "logging_settings": [
 5            {
 6                "verbosity": "WARNING",
 7                "facility": "MIDDLEWARE"
 8            },
 9            {
10                "verbosity": "ERROR",
11                "facility": "SERVICE"
12            }
13        ]
14    },
15    {
16        "application_selector": "//GUID(AAAAAAAA.BBBBBBBB.CCCCCCCC.DDDDDDDD)",
17        "logging_settings": [
18            {
19                "verbosity": "WARNING",
20                "facility": "MIDDLEWARE"
21            },
22            {
23                "verbosity": "ERROR",
24                "facility": "SERVICE"
25            }
26        ]
27    }
28]
Response Headers:
Status Codes:

  • 204 No Content –

    • Description: If successful, this method returns an empty response indicating the collection verbosity level has been set.

  • 400 Bad Request –

    • Description: In case of an invalid input, this method returns a response body with the error code and a message.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 404 Not Found –

    • Description: The application_selector is not found or does not match any application.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 500 Internal Server Error –

    • Description: Generic server error.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

POST /rti/collector_service/rest1/logging:set_forwarding_level

This method sets the Forwarding logging level of a given application_selector.

Request Headers:

  • Content-Length – Transfer-length of the message-body.

  • Content-Type – Valid values: application/json, application/dds-web+json.

  • Authorization – The authorization header is used to authenticate the user. The value of the header is the user’s credentials encoded in base64. The format is “Basic <base64 encoded username:password>”.

Example Request Body:

  • application/dds-web+json

     1[
 2    {
 3        "application_selector": "//app_1",
 4        "logging_settings": [
 5            {
 6                "verbosity": "WARNING",
 7                "facility": "MIDDLEWARE"
 8            },
 9            {
10                "verbosity": "ERROR",
11                "facility": "SERVICE"
12            }
13        ]
14    }
15]
Response Headers:
Status Codes:

  • 204 No Content –

    • Description: If successful, this method returns an empty response indicating the collection verbosity level has been set.

  • 400 Bad Request –

    • Description: In case of an invalid input, this method returns a response body with the error code and a message.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 404 Not Found –

    • Description: The application_selector is not found or does not match any application.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 500 Internal Server Error –

    • Description: Generic server error.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

GET /rti/collector_service/rest1/metrics:get_subscription_state

This method gets the metrics subscription state of a given resource_selector.

Request Headers:

  • Authorization – The authorization header is used to authenticate the user. The value of the header is the user’s credentials encoded in base64. The format is “Basic <base64 encoded username:password>”.

Query Parameters:

  • resource_selector –

    • Description: The resource_selector to get the metrics subscription state.

    • Type: string

    • Required: true

    • Example: //resource_1

      GET http://.../rti/collector_service/rest1/metrics:get_subscription_state?resource_selector=//resource_1 HTTP/1.1

Response Headers:
Status Codes:

  • 200 OK –

    • Description: If successful, this method returns the metrics subscription state for the resources that matched the resource_selector. The list of metrics returned for each resource is enabled for collection.

    • Example Response Body:

      • application/dds-web+json

         1[
 2    {
 3        "resource": "//resource_1",
 4        "metrics": [
 5            "dds_data_writer_protocol_received_nack_bytes_total",
 6            "dds_data_writer_protocol_pulled_samples_total",
 7            "dds_data_writer_protocol_sent_heartbeats_total"
 8        ]
 9    }
10]

  • 400 Bad Request –

    • Description: In case of an invalid input, this method returns a response body with the error code and a message.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 404 Not Found –

    • Description: The resource_selector is not found or does not match any resource.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 500 Internal Server Error –

    • Description: Generic server error.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

POST /rti/collector_service/rest1/metrics:set_subscription_state

This method sets the metrics subscription state of a given resource_selector. The metric names provided in “subscribe_metric_selectors” are enabled for collection and distribution for the selected resource. All other metrics on the selected resource are disabled.

If no metrics match the provided selectors, no error is returned.

Request Headers:

  • Content-Length – Transfer-length of the message-body.

  • Content-Type – Valid values: application/json, application/dds-web+json.

  • Authorization – The authorization header is used to authenticate the user. The value of the header is the user’s credentials encoded in base64. The format is “Basic <base64 encoded username:password>”.

Example Request Body:

  • application/dds-web+json

     1[
 2    {
 3        "resource_selector": "//GUID(AAAAAAAA.BBBBBBBB.CCCCCCCC.EEEEEEEE)",
 4        "subscribe_metrics_selectors": [
 5            "dds_data_writer_protocol_received_nack_bytes_total",
 6            "dds_data_writer_protocol_pulled_samples_total",
 7            "dds_data_writer_protocol_sent_heartbeats_total"
 8        ]
 9    }
10]
Response Headers:
Status Codes:

  • 204 No Content –

    • Description: If successful, this method returns an empty response indicating the metrics subscription state has been set.

  • 400 Bad Request –

    • Description: In case of an invalid input, this method returns a response body with the error code and a message.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 404 Not Found –

    • Description: The resource_selector is not found or does not match any resource.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 500 Internal Server Error –

    • Description: Generic server error.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

POST /rti/collector_service/rest1/metrics:update_subscription_state

This method updates the metrics subscription state of a given resource_selector. The metric names provided in “subscribe_metric_selectors” are enabled for collection and distribution for the selected resource. The metric names provided in “unsubscribe_metric_selectors” are disabled for collection and distribution for the selected resource. The “subscribe_metric_selectors” list is applied before the “unsubscribe_metric_selectors” list. It a metric is in both lists it will be disabled.

If no metrics match the provided selectors, no error is returned.

Request Headers:

  • Content-Length – Transfer-length of the message-body.

  • Content-Type – Valid values: application/json, application/dds-web+json.

  • Authorization – The authorization header is used to authenticate the user. The value of the header is the user’s credentials encoded in base64. The format is “Basic <base64 encoded username:password>”.

Example Request Body:

  • application/dds-web+json

     1[
 2    {
 3        "resource_selector": "//GUID(01234567.89ABCDEF.01234567.89ABCDEF)",
 4        "subscribe_metrics_selectors": [
 5            "dds_data_writer_protocol_received_nack_bytes_total",
 6            "dds_data_writer_protocol_sent_heartbeats_total"
 7        ],
 8        "unsubscribe_metrics_selectors": [
 9            "dds_data_writer_protocol_pulled_samples_total"
10        ]
11    }
12]
Response Headers:
Status Codes:

  • 204 No Content –

    • Description: If successful, this method returns an empty response indicating the metrics subscription state has been set.

  • 400 Bad Request –

    • Description: In case of an invalid input, this method returns a response body with the error code and a message.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 404 Not Found –

    • Description: The resource_selector is not found or does not match any resource.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}

  • 500 Internal Server Error –

    • Description: Generic server error.

    • Example Response Body:

      • application/dds-web+json

        1{
2    "code": "...",
3    "message": "..."
4}