Overview

So far, we've got the soundtracks subgraph running and its schema published, but we still need one piece to tie everything together: the router.

In this lesson, we will:

• Set up the GraphOS Router locally
• Connect our router to GraphOS
• Send our first query to our supergraph
• Explore supergraph insights through the operation and field metrics provided by GraphOS

Downloading the router

The GraphOS Router is a high-performance graph router, available as an executable binary that you can add to your project in a few steps:

Open a terminal window and navigate to the Router directory. So far, we only have the .env file in here with our environment variables and a router-config.yaml file, which we'll get to later.

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 binary file called router!

Router configuration

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

For now, we've set two options: the port that the router should run on (under the supergraph.listen property) and to include all the subgraph errors that bubble up. By default, the 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, we have some telemetry configuration which reduces the kinds of errors we'll see in our terminal output.

Running the router

Back in the same terminal window, run the command below that suits your development environment. You'll need to replace the <APOLLO_KEY> and <APOLLO_GRAPH_REF> placeholder values with your supergraph's corresponding values from the Router/.env file we set up in the previous lesson. This command starts up the router locally, tells the router which supergraph to connect to and makes use of the configuration file.

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, we'll need it to set our connection settings in Studio.

This tells outside consumers of our API what endpoint they can use to query our schema.

Connecting the router to GraphOS

Let's flip 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.

Let's get to querying our supergraph!

Testing our schema

Select the Explorer tab from the sidebar.

Let's put together a query that retrieves the titles and descriptions of our featured playlists.

Now let's run this query.

Fantastic, we get back our list of featured playlists.

GraphOS provides us with observability tools to monitor the health and performance of our supergraph. These tools help surface patterns in how our supergraph gets used, which helps us continue to improve it. We're still in tutorial-land, so there isn't any real production traffic going to our supergraph, but we can still check out our supergraph insights!

Run the operations below a few more times to see some data pop up before we check out the metrics.

Operation metrics

Let's navigate over to the Insights page.

The Operations tab gives us an overview of operation request rates, service time, and error percentages, including specific operations for each of these that might be worth drilling deeper into.

We recommend that clients clearly name each GraphQL operation they send to the supergraph, so we can easily view them in our metrics.

We can also filter to select a particular operation to 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.

Beside each field, we'll see the total number of requesting operations, which is the number of operations in a given period that have included that particular field.

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.

Practice

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.

Up next

We're going to 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!