5. Router configuration & insights
5m

Overview

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

In this lesson, we will:

  • Set up the locally
  • Connect our to
  • Send our first to our
  • Explore insights through the and metrics provided by

Downloading the router

The 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.

📦 Router
┣ 📄 router-config.yaml
┗ 📄 .env

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

Router
curl -sSL https://router.apollo.dev/download/nix/v1.37.0 | sh

Note: Visit the official documentation to explore alternate methods of downloading the Router.

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

📦 Router
┣ 📄 router-config.yaml
┣ 📄 .env
┗ 📄 router

Router configuration

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

router-config.yaml
supergraph:
listen: 127.0.0.1:5000
include_subgraph_errors:
all: true
telemetry:
instrumentation:
spans:
mode: spec_compliant

For now, we've set two options: the port that the should run on (under the supergraph.listen property) and to include all the errors that bubble up. By default, the 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.

Note: To learn more about other options available for configuring the , check out the documentation.

Running the router

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

APOLLO_KEY=<APOLLO_KEY> APOLLO_GRAPH_REF=<APOLLO_GRAPH_REF> ./router --config router-config.yaml

We'll see a few lines of 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.

http://127.0.0.1:5000

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

Note: Because our is currently running at http://127.0.0.1:5000, it's not actually accessible to the outside world. But we can still add the from our own machines.

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.

https://studio.apollographql.com

Studio - README

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

https://studio.apollographql.com

Studio - Connection Settings

Let's get to our !

Testing our schema

Select the Explorer tab from the sidebar.

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

query GetFeaturedPlaylists {
featuredPlaylists {
id
name
description
}
}

Now let's run this .

https://studio.apollographql.com

Explorer - query featured playlists

Fantastic, we get back our list of featured playlists.

provides us with observability tools to monitor the health and performance of our . 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 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.

https://studio.apollographql.com

Insights page in Studio, showing Operations tab

The Operations tab gives us an overview of 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 they send to the , so we can easily view them in our metrics.

We can also filter to select a particular to see more specific details about its usage, as well as its signature, which is the shape of the . We can see the number of requests that have been made and how long each request takes over time.

https://studio.apollographql.com

Operations page filter for a specific operation in Studio

Field metrics

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

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

https://studio.apollographql.com

Fields page in Studio

We can use both and metrics to monitor the health and usage of our '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

Which of the following operation metrics does GraphOS provide?

Key takeaways

  • metrics provide an overview of operation request rates, service time, and error percentages within a given time period or for a specific operation.
  • metrics include the requesting 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 : 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!

Previous

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.