Connector Observability

Apollo provides a few ways to understand your connectors' behavior and performance:

• You can view query plans to understand when REST APIs are called in the context of subgraph operations.

• You can view and export traces to understand operation performance, including REST API calls.

• You can configure router telemetry for connectors.

Understand connector runtime with query plans

Whenever a supergraph receives an incoming GraphQL operation, its router generates a query plan with the steps necessary to efficiently resolve the operation from any number of data sources. Typically, those data sources are GraphQL subgraphs. With connectors they can also be REST APIs.

Query plan example

Suppose these two subgraphs are part of the same supergraph:

1type Query {
2  products: [Product]
3}
4
5type Product @key(fields: "id") {
6  id: ID!
7  name: String
8}
9
10type User @key(fields: "id") {
11  id: ID!
12  name: String
13}

Subgraph A provides the Query.products root field and provides ids and names for Products and Users. Notice that both Product and User are entities that both subgraphs can access and contribute to.

1type Product @key(fields: "id") {
2  id: ID!
3  reviews: [Review]
4    @connect(
5      http: { GET: "/reviews?product_id={$this.id}" }
6      selection: """
7      $.results {
8        id
9        rating
10      }
11      """
12    )
13}
14
15type Query {
16  review(id: ID!): Review
17    @connect(
18      http: { GET: "/reviews/{$args.id}" }
19      selection: """
20      id
21      rating
22      content
23      author: { id: author_id }
24      """
25      entity: true
26    )
27}
28
29type Review {
30  id: ID!
31  rating: Int
32  content: String
33  author: User
34}
35
36type User @key(fields: "id", resolvable: false) {
37  id: ID!
38}

Subgraph B uses connectors to extend the Product entity with review data from a REST API. It also provides an entity resolver for the Review type to provide more fields. Notice that the Review.author references the User entity using the foreign key author_id.

A client could send the following GraphQL request to the supergraph these subgraphs are composed into:

1query ProductList {
2  products {
3    id
4    name
5    reviews {
6      id
7      rating
8      content
9      author {
10        id
11        name
12      }
13    }
14  }
15}

To fulfill this request, the query plan would have these four steps:

1. Fetch Query.products and Product.id and Product.name from Subgraph A.

2. Use Product entity references to fetch Product.reviews. Because Product.reviews is a connector, the GraphOS Router calls the REST API directly.

3. Because /reviews doesn't provide the full review data, the GraphOS Router calls /reviews/{id} for each review to fetch the rest of the Review fields.

4. Use User entity references to fetch User.name from Subgraph A.

1QueryPlan {
2  Sequence {
3    Fetch(service: "subgraph-a") {
4      {
5        products {
6          __typename
7          id
8          name
9        }
10      }
11    },
12    Flatten(path: "products.@") {
13      Fetch(service: "subgraph-b.reviews http: GET /reviews?product_id={$this.id}") {
14        {
15          ... on Product {
16            __typename
17            id
18          }
19        } =>
20        {
21          ... on Product {
22            reviews {
23              __typename
24              id
25              rating
26            }
27          }
28        }
29      },
30    },
31    Flatten(path: "products.@.reviews.@") {
32      Fetch(service: "subgraph-b.reviews http: GET /reviews/{$args.id!}") {
33        {
34          ... on Review {
35            __typename
36            id
37          }
38        } =>
39        {
40          ... on Review {
41            author {
42              __typename
43              id
44            }
45            content
46          }
47        }
48      },
49    },
50    Flatten(path: "products.@.reviews.@.author") {
51      Fetch(service: "subgraph-a") {
52        {
53          ... on User {
54            __typename
55            id
56          }
57        } =>
58        {
59          ... on User {
60            name
61          }
62        }
63      },
64    },
65  },
66}

Observe performance with traces

Traces monitor the flow of a request through the GraphOS Router. You can view operation traces in GraphOS Studio or use the GraphOS Router to export them to monitoring tools.

Operation traces

Individual operation metrics in GraphOS Studio include operation traces if you've enabled trace reporting.

When you view operation traces in GraphOS Studio, Apollo Connectors appear as span parents. These spans give a general idea of request latency.

Cloud-native traces

The GraphOS Router emits traces that instrument the execution of Apollo Connectors. These traces show individual HTTP requests and are more comprehensive than the traces displayed in GraphOS Studio. To learn more, see router tracing.