6. Publishing to GraphOS
4m

Overview

Let's plate up our changes and send them out to GraphOS! 🍽️

In this lesson, we will:

  • Publish changes to
  • Learn about trace metrics and how to analyze them in Studio
  • Learn how to turn on sources

Publishing to GraphOS

Here's how we land our local changes to production:

  1. Run locally to validate that our changes don't break current functionality.

  2. Merge our codebase changes to GitHub.

  3. Deploy the runtime code for the to Railway (this happens automatically, Railway is listening for changes to our GitHub main branch).

  4. Publish the to . This triggers a , which when successfully completed, will compose a new for the to use.

If you've completed GraphOS: Safe API delivery, you'll be familiar with this process, and you might even have CI/CD set up to take care of everything 😎 Go ahead and follow the process! If you need a refresher, head over to Lesson 7: Field insights of the course and refer to the "Deploying our changes" section.

If you haven't completed the course, no worries! If you'd like to learn more about each command we'll be running and how to integrate the process into a CI/CD workflow, that course goes deep into all the details. For now, we'll walk you through it, rapid-fire style, and we'll use manual commands.

  1. First, let's run . In a new terminal, run the command below. Replace <GRAPH_REF> below with your own!

    rover subgraph check <GRAPH_REF> \
    --schema ./schema.graphql \
    --name recipes

    We should receive a message saying that one new has been added (the cookware ) and everything is passing. Hooray! We won't be making any breaking changes to our .

  2. Next, let's add and commit our changes.

    git checkout -b feature/recipe-cookware
    git add .
    git commit -m "Add Recipe.cookware to subgraph."
  3. Next, we'll push our changes to Github, straight to the main branch.

    git push -u origin main
  4. This will trigger a deploy in Railway. Head on over to your application on Railway and monitor its progress. When it's ready, head back to GitHub.

  5. The codebase changes have been deployed, so let's make sure our schema is up to date in . We'll run a rover subgraph publish command. Again, replace the <GRAPH_REF> below with your own!

    rover subgraph publish <GRAPH_REF> \
    --schema ./schema.graphql \
    --name recipes

    This triggers a !

  6. Jump over to Studio in your browser and navigate to the Launches page. We'll wait for the to show green checkmarks and the "Deployed" label before moving on to the next section.

    https://studio.apollographql.com/

    Launches page in Studio

Subgraph changes in Studio

Let's see our changes in action! Head over to Explorer so we can run that dream of ours again, this time in production.

query GetRecipeAndCookwareInformation {
recipe(id: "rec3j49yFpY2uRNM1") {
name
description
ingredients {
text
}
instructions
cookware {
name
description
cleaningInstructions
}
}
}

Nice! We had this all working locally with rover dev before, so we were fairly confident about the change, but now we can validate it 100%!

Let's check out some other cool things while we're here.

In the Documentation panel on the left, click the gear icon to access the Settings.

https://studio.apollographql.com/

Explorer, Settings gear icon

Scroll down to the Editor hints section and toggle them on. Select Subgraph source. Now we can see which each is coming from, inline with our .

https://studio.apollographql.com/

Explorer, Editor hints in Settings

Let's take a peek at the the created for this specific . Click the arrow next to Response and select Query Plan Preview.

https://studio.apollographql.com/

Explorer, Query Plan Preview

We can view this as a chart, or as text if we select the icon to "Show plan as text". We won't worry too much about the syntax– the knows what's going on! But this is useful when we start to involve more and more complex queries that need optimization.

https://studio.apollographql.com/

Explorer, Editor hints in Settings

Let's send a few more to our before we move on to investigating trace metrics! Run that dream a few more times!

Trace metrics

A trace shows the execution of a single from start to finish. It includes a breakdown of the timing and error information for each resolved in that operation.

In a , we have federated traces, which are constructed from timing and error information provided by our .

Both our recipes and kitchenware use the @apollo/subgraph library, so these federated traces are enabled by default and we don't need to do anything extra!

Note: If you're using a different library, you can consult this list in the Apollo documentation to determine if it supports federated tracing and how to enable it.

With traces, we can start to see which or are taking a long time to resolve, which helps us identify where we can make improvements!

To access traces, head to the Operations page in Studio. Select an from the dropdown.

https://studio.apollographql.com/

Operations page in Studio

When we select a particular , we can see more specific details about this operation's usage, as well as its signature (which is the shape of the ). We can see the request rate (the number of requests that have been made), and the latency of the request (how long each request takes) over time.

Let's take a look at the Traces tab.

https://studio.apollographql.com/

A selected operation's Traces tab in Studio

saves one sample trace per latency bucket, so we can select a bar from the chart to analyze that particular trace and observe the timing details for that particular .

Pretty handy! For each , we can dig further into the time it takes for each to resolve its . From there, we can tweak and improve as necessary!

Practice

Which of the following can be shown as inline hints for each field of a query in Explorer?
Which of the following are ways in which you can view the router's query plan?
Which of these are included in a federated trace?

Key takeaways

  • Using rover dev for local development, in conjunction with , helps us validate and test changes before pushing them to a in production.
  • A federated trace provides a breakdown of timing and error information for each in a particular , as provided by the .

Conclusion

You've reached the end, well done!

You've got all the ingredients for success to grow your to your heart's content. In this course, we learned how to quickly add a with a few clicks of a button in Studio. We got our hands dirty with local development and used rover dev to run a router locally: a playground to explore and dream up new features. We dipped our toes into the world of federation, learning what entities are and how to use them to connect data between subgraphs. Lastly, we shipped our changes to production, bringing the improved version of Poetic Plates to the world – now with kitchenware! 🍳

What's next? We're cooking up more things to help you on your journey.

In the meantime, why not dive into the with our Voyage series? You can start with Voyage I: Federation from Day One.

See you in the next one!

Previous

Share your questions and comments about this lesson

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.