4. Running the router
10m

Overview

We've taken care of two of our steps on the journey from to . 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 to different services. Next up: let's get our running!

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

The GraphOS Router

The is a high-performance graph router, available as an executable binary that you can configure in just a few steps.

Installing the router

Open up a new terminal window and navigate 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 router-config.yaml. This is a configuration file which lets us customize certain aspects about how the runs.

📦 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.46.0 | sh

We'll see some installation output, then an instruction on how to start the .

You can now run the Apollo Router using './router'

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 file also 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 a few options, including the port that the should run on (under the supergraph.listen property). We also configured a setting 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

Next up: we'll tell the which to connect to, and how to authenticate to it.

For that, we'll use those two specific pieces of data we copied from the creation process: our APOLLO_KEY and APOLLO_GRAPH_REF values!

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

Terminal opened to the router directory
APOLLO_KEY=<APOLLO_KEY> APOLLO_GRAPH_REF=<APOLLO_GRAPH_REF> ./router --config router-config.yaml

Notice the --config flag we're including in our command? This tells the to use the settings we've included in 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.

http://127.0.0.1:5000/

This is the entrance to our : if this were a production URL, it's where anyone any part of our schema would send their requests to! For this course, we'll keep our running locally on port 5000—so let's add this detail to !

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.

studio.apollographql.com

The graph README page, highlighting that the graph does not yet have an endpoint

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

studio.apollographql.com

The connection settings modal, highlighting the input where we can paste our endpoint

Testing our schema

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

query GetFeaturedListings {
featuredListings {
id
title
description
}
}

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

Though our and listings are running locally, we've got all the pieces in place for production!

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 , but we can still check out our supergraph insights.

Operation metrics

Let's navigate over to the Insights page.

studio.apollographql.com

The Insights page in Studio

The Operations tab in the first panel on the left 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.

studio.apollographql.com

The Insights page in Studio, filtered to show metrics for a specific operation: GetFeaturedListings

Field metrics

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

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

studio.apollographql.com

The Insights page in Studio, on the Fields tab

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

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've reviewed our metrics, and we're ready for our to grow. In the next lesson, we'll introduce a whole new domain in the form of a new , all about reviews!

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.