Overview

Our soundtracks API is now reporting to GraphOS—but we still need to start up our router to pull the pieces together.

In this lesson, we will:

• Run the Apollo Router
• Explore supergraph metrics
• Describe how the router creates query plans to resolve GraphQL operations across multiple subgraphs

The Apollo Router

We've taken care of two of our steps on the journey from subgraph to supergraph. We've centralized a place in Studio for all of the details about our graph to live—but we're still missing the piece that routes different parts of our query to different services. Next up: let's get our router running!

The Apollo Router is a high-performance graph router written in Rust. It's available as an executable binary that you can configure in just a few steps.

Installing the router

In the terminal, let's navigate up a level in our project, then into the router directory. So far, we have the .env file in here with our environment variables (APOLLO_GRAPH_REF and APOLLO_KEY), along with a file called config.yaml. This is a configuration file which lets us customize certain aspects about how the router runs.

We'll download the router by running the install command in the terminal.

Now when we check the contents of our router directory, we'll see that we have a new file also called router!

Router configuration

Let's take a peek inside the config.yaml file. This file enables us to customize our router's behavior.

For now, we've set a few options, including the port that the router should run on (under the supergraph.listen property). We also configured a setting to include all the subgraph errors that bubble up. By default, the Apollo Router redacts the details of subgraph errors in its responses, and we might see an error message like "Subgraph errors redacted". In production environments, this property is usually set to false, but it'll be helpful if you run into any issues following along in this tutorial.

Lastly, our config.yaml file has some telemetry configuration which reduces the kinds of errors we'll see in our terminal output.

Running the router

Next up: we'll tell the router which supergraph to connect to, and how to authenticate to it. This means that we'll pass it our APOLLO_KEY and APOLLO_GRAPH_REF values!

From the router directory, run the command below, replacing the placeholder <APOLLO_KEY> and <APOLLO_GRAPH_REF> with your values from .env.

We'll see a few lines of router output, and finally a message that our router is running on port 5000, ready to receive queries!

Let's copy this address.

This is the entrance to our graph: it's where anyone querying any part of our schema will send their requests to. Let's add this detail to GraphOS!

Connecting the router to GraphOS

Flipping back over to Studio, click on the README tab in the sidebar. Next, tap the Connection Settings link at the top of the page.

We'll paste the router address we copied (http://127.0.0.1:5000) as the endpoint, then save.

Testing our schema

Let's put together a query that retrieves the titles and descriptions of our featured playlists. Select the Explorer tab from the sidebar and paste in the following operation.

Now let's run this query, and... fantastic! We've got data!

GraphOS Studio and the supergraph

Though our router and soundtracks subgraph are running locally, we've got all the pieces in place for production: our router can receive requests, and it consults the supergraph schema in GraphOS to know where each piece of a query should be sent. Right now, it only has one subgraph to worry about: all requests will land in our soundtracks subgraph to be fulfilled!

Even so, GraphOS has already gathered insights about our API: we can see what has been queried for, how many times, and if any errors were encountered. Let's jump into our supergraph metrics in Studio.

Operation metrics

First, we'll check out the Insights page.

The Operations tab in the first panel on the left gives us an overview of operation request rates, service time, and error percentages, as well as specifics for each individual operation we wish to inspect.

By filtering this page to a particular operation, we'll see more specific details about its usage, as well as its signature, which is the shape of the query. We can see the number of requests that have been made and how long each request takes over time.

Field metrics

Next, let's check out field metrics. Head over to the Fields tab.

For each field, we can explore more specific datapoints, including the number of requests that have included it.

We can use both operation and field metrics to monitor the health and usage of our supergraph's types and fields and determine where we can start to improve, based on how they're performing and how our clients are using them. Because we can see which fields our clients are using AND how frequently, these metrics also let us know when it's safe to remove unused fields from our graph.

We've reviewed our metrics, and we're ready for our supergraph to grow: next, let's take a look at how we keep adding pieces to our API.

Key takeaways

• Operation metrics provide an overview of operation request rates, service time, and error percentages within a given time period or for a specific operation.
• Field metrics include the requesting operations metric, which lists the number of operations in a given period that have included the particular field.
• The router uses the supergraph schema to create a query plan for the incoming GraphQL operation. The query plan is a list of smaller operations the router can execute on different subgraphs to fully resolve the incoming operation.
• The router carries out the query plan by executing the list of operations on the appropriate subgraphs.
• The router combines all the responses from the subgraphs into a single JSON object, which it sends back to the client.

Up next

Let's see this process in action! In the next lesson, we'll introduce a whole new domain in the form of a new subgraph: it's an activity we're all familiar with, and it's much more fun when we've got music to set the mood. It's a subgraph all about recipes!