Connector Telemetry Configuration

Collect observable data to monitor your Connectors

Requires ≥ Router v2.0.0

Connector telemetry provides visibility into how your graph is interacting with your REST APIs. Telemetry helps you monitor performance metrics, detect issues early, and gain insights into API behavior patterns.

You configure telemetry via your router. This page lists telemetry attributes, instruments, and events available for Connectors. Refer to the router telemetry docs for both a telemetry overview and details. See the Connector troubleshooting guide's debugging section for information on how to add debug information to telemetry.

Attributes

Attributes can be attached to telemetry such as instruments and events. These attributes are used to filter and group data in your application performance monitor (APM).

The following standard attributes are available for Connectors:

AttributeDescription
subgraph.nameThe name of the subgraph containing the Connector
connector.source.nameThe name of the @source associated with this Connector, if any
connector.http.methodThe HTTP method for the Connector (GET or POST, for example)
connector.url.templateThe URL template for the Connector

Selectors

A selector is used to extract data from Connectors requests and responses and attach the data to telemetry such as instruments and events.

Apollo Connectors for REST APIs make HTTP calls to the upstream HTTP API. The selectors in the following table let you extract metrics from these HTTP requests and responses.

SelectorDefaultableValuesDescription
subgraph_nameNotrue|falseThe name of the subgraph containing the Connector
connector_source NonameThe name of the @source associated with this Connector, if any
connector_http_request_headerYesThe name of a Connector request header
connector_http_response_headerYesThe name of a Connector response header
connector_http_response_statusNocode|reasonThe status of a Connector response
connector_http_methodNotrue|falseThe HTTP method of a Connector request
connector_url_templateNotrue|falseThe URL template of a Connector request
connector_request_mapping_problemsNoproblems|countAny mapping problems with the Connector request
connector_response_mapping_problemsNoproblems|countAny mapping problems with the Connector response
staticNoA static string value
errorNoreasonA string value containing error reason when it's a critical error

Instruments

An instrument in the router collects data and reports measurements to a metric backend. Supported instruments include standard instruments from OpenTelemetry, standard instruments for the router request lifecycle, and custom instruments. Supported instrument kinds are counters and histograms.

You can configure instruments in router.yaml with telemetry.instrumentation.instruments.

OpenTelemetry standard instruments

OpenTelemetry specifies multiple standard metric instruments that are available for Connectors HTTP requests and responses:

  • http.client.request.body.size - A histogram of request body sizes for Connectors HTTP requests.

  • http.client.request.duration - A histogram of request durations for Connectors HTTP requests.

  • http.client.response.body.size - A histogram of response body sizes for Connectors HTTP responses.

These instruments are configurable in router.yaml:

YAML
router.yaml
telemetry:
  instrumentation:
    instruments:
      connector:
        http.client.request.body.size: true
        http.client.request.duration: true
        http.client.response.body.size: true

The default_requirement_level setting configures whether or not these instruments are enabled by default. They can be customized by attaching or removing attributes. See attributes to learn more about configuring attributes.

YAML
router.yaml
telemetry:
  instrumentation:
    instruments:
      connector:
        http.client.request.duration:
          attributes:
            connector.source.name: true

Custom instruments

plan required
This feature is only available with a GraphOS plan. You can test it out by signing up for a Free plan. To compare GraphOS feature support across all plan types, see the pricing page.

You can define custom instruments on Connectors HTTP requests and responses.

For example, the following custom instrument provides the number of 404 response statuses from a specific REST API:

YAML
router.yaml
telemetry:
  instrumentation:
    instruments:
      connector:
        acme.user.not.found:
          value: unit
          type: counter
          unit: count
          description: "Count of 404 responses from the user API"
          condition:
            all:
              - eq:
                  - 404
                  - connector_http_response_status: code
              - eq:
                  - "user_api"
                  - connector_source: name

See the router documentation for more details about configuring instruments.

Events

An event is used to signal when something of note happens, such as a Connector request or response.

You can configure events for each service in router.yaml. Events can be standard or custom, and they can be triggered by configurable conditions.

See the router documentation for more details about configuring events.

Standard events

Standard events can be configured for Connectors. The following enables standard Connector HTTP response events at the INFO level:

YAML
router.yaml
events:
  connector:
    request: off
    response: info
    error: error

Custom events

Custom events can also be configured for Connectors. The following example defines a custom event for each Connector HTTP response at the INFO level:

YAML
router.yaml
events:
  connector:
    connector.response:
      message: "Connector response"
      level: info
      on: response
      attributes:
        connector.http.method: true
        connector.url.template: true
        response_status:
          connector_http_response_status: code

If you have a stdout logging exporter, the router logs each Connector response with the attributes defined above:

Text
1INFO  connector.http.method=GET connector.url.template=/users response_status=200 Connector response kind=connector.response
2INFO  connector.http.method=GET connector.url.template=/users/{$this.id}/posts response_status=200 Connector response kind=connector.response
Feedback

Ask Community