diff --git a/docs/source/intro/benefits.md b/docs/source/intro/benefits.md index 938b19e..8dd17d2 100644 --- a/docs/source/intro/benefits.md +++ b/docs/source/intro/benefits.md @@ -9,7 +9,7 @@ Adopting GraphQL in your organization will ease these pain points considerably. ## Developer experience -Implementing GraphQL in your organization via the Apollo platform can help you ship features faster due to its excellent developer experience. Our #1 goal is to simplify data management across the stack. Features that are normally difficult to execute, such as fullstack caching, data normalization, and optimistic UI suddenly become trivial thanks to Apollo Client, Apollo Server, and Apollo Engine. Let's learn how! +Implementing GraphQL in your organization via the Apollo platform can help you ship features faster due to its excellent developer experience. Our #1 goal is to simplify data management across the stack. Features that are normally difficult to execute, such as fullstack caching, data normalization, and optimistic UI suddenly become trivial thanks to Apollo Client, Apollo Server, and Apollo Graph Manager. Let's learn how! ### Explore your API @@ -47,9 +47,9 @@ Teams who have switched to Apollo Client have reported [deleting thousands of li Developing your GraphQL API with the Apollo platform gives teams access to modern tooling that helps them uncover bugs quickly, gain visibility into their API, and develop challenging features such as caching with confidence. -[Apollo Engine](https://engine.apollographql.com/login) is the only tool in the GraphQL ecosystem that can provide monitoring and analytics for your API. Apollo Engine displays per resolver tracing metrics that can help you pinpoint bugs, as well as performance distribution for every field in your schema. You can also pipe this data to services you're probably already using like DataDog, and set up Slack alerts if these numbers pass a certain threshold. +[Apollo Graph Manager](https://engine.apollographql.com/login) is the only tool in the GraphQL ecosystem that can provide monitoring and analytics for your API. Graph Manager displays per-resolver tracing metrics that help you pinpoint bugs, as well as performance distribution for every field in your schema. You can also pipe this data to services you're probably already using like DataDog, and set up Slack alerts if these numbers pass a certain threshold. -![Apollo Engine](../assets/engine.png) +![Apollo Graph Manager](../assets/engine.png) ## Declarative data fetching diff --git a/docs/source/old/performance.md b/docs/source/old/performance.md index 84c90ea..8f35b5b 100644 --- a/docs/source/old/performance.md +++ b/docs/source/old/performance.md @@ -168,4 +168,4 @@ If configured correctly, browser's dev tools should verify that queries are now How exactly this works depends on exactly which CDN you chose. Configure your CDN to send requests to Apollo Server. Some CDNs may need to be specially configured to honor origin Cache-Control headers; for example, here is [Akamai's documentation on that setting](https://learn.akamai.com/en-us/webhelp/ion/oca/GUID-57C31126-F745-4FFB-AA92-6A5AAC36A8DA.html). If all is well, cacheable queries should now be saved by the CDN! -> Note that requests served directly by a CDN will not show up in the Engine dashboard. +> Note that requests served directly by a CDN will not show up in the Graph Manager dashboard. diff --git a/docs/source/platform/client-awareness.md b/docs/source/platform/client-awareness.md index 09fac02..6d7ae3b 100644 --- a/docs/source/platform/client-awareness.md +++ b/docs/source/platform/client-awareness.md @@ -9,7 +9,7 @@ Apollo provides a client identification and tracking system, which allows you to Like any API, your graph will end up with many consumers with different frequencies, subselections, and permissions as it grows over time. Apollo allows all reported data to be tagged with client information so it can be filtered and analyzed across different sets of clients and stacks. -Here's an example of client identity reporting in Engine: +Here's an example of client identity reporting in Apollo Graph Manager: ![client overview](../img/client-awareness/overview.png) diff --git a/docs/source/platform/editor-plugins.md b/docs/source/platform/editor-plugins.md index 40042a2..be6bcf3 100644 --- a/docs/source/platform/editor-plugins.md +++ b/docs/source/platform/editor-plugins.md @@ -25,7 +25,7 @@ The [VS Code extension](https://marketplace.visualstudio.com/items?itemName=apol To get all of the benefits of the VS Code experience, it's best to link the schema that is being developed against **before** installing the extension. The best way to do that is by [publishing a schema](/platform/schema-registry/#registering-a-schema) to the Apollo schema registry. Once that is done, two steps are needed: 1. Create an `apollo.config.js` at the root of the project -2. Copy an API key from the Engine dashboard of the published service +2. Copy an API key from the Graph Manager dashboard of the published service ### Setting up an Apollo config @@ -39,13 +39,13 @@ module.exports = { }; ``` -The `service` name here is the ID of the graph you've created in [Engine](https://engine.apollographql.com). +The `service` name here is the ID of the graph you've created in [Apollo Graph Manager](https://engine.apollographql.com). -> **Note:** The ID of your graph can be found in its URL in Engine. We use the ID so you can change your graph's name freely without having to update this. This will be easier to manage in the future. +> **Note:** The ID of your graph can be found in its URL in Graph Manager. We use the ID so you can change your graph's name freely without having to update this. This will be easier to manage in the future. ### Setting up an API key -To authenticate with Engine to pull down the schema, create a file next to the `apollo.config.js` called `.env`. This should be an untraced file (i.e. don't push it to GitHub). Go to the settings page of your graph in Engine to get the API key. +To authenticate with Graph Manager to pull down the schema, create a file next to the `apollo.config.js` called `.env`. This should be an untraced file (i.e., don't push it to GitHub). Go to the settings page of your graph in Graph Manager to get the API key. > **Note:** It is best practice to create a new API key for each member of the team and name the key so its easy to find and revoke if needed. This will be easier to manage in the future. @@ -55,7 +55,7 @@ After the key is found, add the following line to the `.env` file: ENGINE_API_KEY= ``` -After this is done, VS Code can be reloaded and the Apollo integration will connect to Engine to provide autocomplete, validation, and more. +After this is done, VS Code can be reloaded and the Apollo integration will connect to Graph Manager to provide autocomplete, validation, and more. ### Local schemas @@ -126,7 +126,7 @@ GraphQL's flexibility can make it difficult to predict the cost of an operation. To turn on tracing for your GraphQL server, please visit our [guide](/references/setup-analytics/). -The VS Code extension will show inline performance diagnostics when connected to a service with reported metrics in Engine. As operations are typed, any fields that take longer than 1ms to respond will be annoated to the right of the field inline! This gives team members a picture of how long the operation will take as more and more fields are added to operations or fragments. +The VS Code extension will show inline performance diagnostics when connected to a service with reported metrics in Graph Manager. As operations are typed, any fields that take longer than 1ms to respond will be annoated to the right of the field inline! This gives team members a picture of how long the operation will take as more and more fields are added to operations or fragments. Performance annotation next to a field diff --git a/docs/source/platform/federation.mdx b/docs/source/platform/federation.mdx index 3e607db..00fabf8 100644 --- a/docs/source/platform/federation.mdx +++ b/docs/source/platform/federation.mdx @@ -139,7 +139,6 @@ Traces will be reported in the shape of the query plan, with each unique fetch t Operation-level statistics will still be collected over the operations sent by the client, and those operations will be validated as part of the `service:check` validation workflow. - ## Validating changes to the graph Federation allows teams to work independently on federated services without needing to coordinate over an all-encompassing schema. However, this increase in autonomy requires control to ensure that teams that operate on different services are respecting [defined dependencies](https://www.apollographql.com/docs/apollo-server/federation/federation-spec/) and not breaking the ability for the graph to compose. The Apollo platform provides tools to help ensure that this increase in autonomy doesn't come at a cost to stability. @@ -148,7 +147,7 @@ In particular, along with [validating overall schema changes against known opera With a federated graph, use the `apollo service:check` command to validate individual service changes by adding the `--serviceName` flag. -When running `apollo service:check` on a federated service, Engine will run composition on the proposed capabilities with the current list of federated services and their capabilities, making sure that the composition is successful. That composed schema will then be diff'ed against the most recently registered schema and validate that those changes are safe. If composition fails, then validation ends and the results will be returned to the user. Note that running `apollo service:check` will never update the graph. +When running `apollo service:check` on a federated service, Apollo Graph Manager will run composition on the proposed capabilities with the current list of federated services and their capabilities, making sure that the composition is successful. That composed schema will then be diff'ed against the most recently registered schema and validate that those changes are safe. If composition fails, then validation ends and the results will be returned to the user. Note that running `apollo service:check` will never update the graph. There are two types of failures that can occur during validation: failed usage checks and failed composition. Failed usage checks are failures due to breaking changes, like removing a field that an active client is querying. Failed composition, on the other hand, is a failure due to inability to compose the graph, like missing an @key for an extended type. diff --git a/docs/source/platform/integrations.md b/docs/source/platform/integrations.md index bb3c98b..2650df8 100644 --- a/docs/source/platform/integrations.md +++ b/docs/source/platform/integrations.md @@ -7,7 +7,7 @@ One of our fundamental beliefs is that our Apollo workflows should hook into and 1. [**GitHub**](#github) — Ensure the safe evolution of your graph by adding schema change validation directly to your continuous integration and GitHub checks. 1. [**Slack**](#slack) — Get a daily summary of key information from your server, including the overall request rate, error rate, and performance latency. Set up notifications for noteworthy events in your service, like increases in errors or particularly slow response times for important queries. -1. [**Datadog**](#datadog) — Forward the key metrics and performance data available from Engine to Datadog as well. +1. [**Datadog**](#datadog) — Forward the key metrics and performance data available from Graph Manager to Datadog as well. ## GitHub @@ -17,7 +17,7 @@ Building tools to help you safely collaborate on the evolution of your graph is ### Install the GitHub application -Go to [https://github.com/apps/apollo-engine](https://github.com/apps/apollo-engine) and click the `Configure` button to install the Apollo Engine integration on the GitHub profile or organization that you want to set up checks for. +Go to [https://github.com/apps/apollo-engine](https://github.com/apps/apollo-engine) and click the `Configure` button to install the Apollo Graph Manager integration on the GitHub profile or organization that you want to set up checks for. ### Run validation on each commit @@ -55,7 +55,7 @@ jobs: - run: apollo service:check # When running on the 'master' branch, publish the latest version - # of the schema to Apollo Engine. + # of the schema to Apollo Graph Manager. - run: | if [ "${CIRCLE_BRANCH}" == "master" ]; then apollo service:push @@ -64,36 +64,36 @@ jobs: > **Note:** Your `apollo service:check` command needs a source to from which to fetch your schema. This is most commonly provided as a URL to a running server (with introspection enabled), but can also be provided as a path to a file with your schema in it. See [Using the Schema Registry](/platform/schema-registry/#using-the-schema-registry) setup for other options. -The `apollo schema:check` command checks for differences in your schema between what's on your current branch and the last version you uploaded to Engine. If you've removed or changed any types or fields, it will validate that those changes won't break any of the queries that your clients have made recently. If your changes do break any queries, the check will fail. +The `apollo schema:check` command checks for differences in your schema between what's on your current branch and the last version you uploaded to Graph Manager. If you've removed or changed any types or fields, it will validate that those changes won't break any of the queries that your clients have made recently. If your changes do break any queries, the check will fail. -Because you installed the Engine app on GitHub, the check you've added will show up as a line in your GitHub checks list. If there are changes in your schema you'll be able to review them by clicking the "Details" link. By enabling schema validation in your continuous integration workflow (eg. CircleCI, etc.), you're alerting developers of any potential problems directly in their pull requests, thereby giving them critical feedback where it's most useful. +Because you installed the Graph Manager app on GitHub, the check you've added will show up as a line in your GitHub checks list. If there are changes in your schema you'll be able to review them by clicking the "Details" link. By enabling schema validation in your continuous integration workflow (eg. CircleCI, etc.), you're alerting developers of any potential problems directly in their pull requests, thereby giving them critical feedback where it's most useful. ## Slack -Our Apollo Slack integration brings your server's performance metrics and analytics data from Apollo Engine directly to your team's Slack workspace so you can be notified of potential issues proactively. The integration does two main things: +Our Apollo Slack integration brings your server's performance metrics and analytics data from Apollo Graph Manager directly to your team's Slack workspace so you can be notified of potential issues proactively. The integration does two main things: 1. Send a [**daily snapshot**](#daily-reports) of the request rate, error rate, and performance latency of your graph. 1. Send [**notifications**](#notifications) that are triggered on thresholds like error percentage and performance latency. ### Configure the integration -The Apollo Slack integration is set up and configured through the Engine UI. If you do not yet have account, [**follow this guide**](https://www.apollographql.com/docs/apollo-server/features/metrics/#Apollo-Engine) to get started connecting your server to Engine. +The Apollo Slack integration is set up and configured through the Graph Manager UI. If you do not yet have account, [**follow this guide**](https://www.apollographql.com/docs/apollo-server/features/metrics/#Apollo-Graph-Manager) to get started connecting your server to Graph Manager. -If you already have an Engine account, [**log in**](https://engine.apollographql.com) and –– +If you already have a Graph Manager account, [**log in**](https://engine.apollographql.com) and –– 1. Select the service you want to turn on Slack notifications for. 1. Visit the "Integrations" tab in the left nav. -1. You'll notice a "Reporting Channels" section at the bottom of this page. Click the "Add channel" button and follow the steps in the Engine UI to get a webhook from Slack. +1. You'll notice a "Reporting Channels" section at the bottom of this page. Click the "Add channel" button and follow the steps in the Graph Manager UI to get a webhook from Slack. Once you've configured your Slack channel you'll be able to turn on daily reports snapshotting and configure notifications in the "General" and "Performance Alerts" sections. -![The Integrations tab in Engine](../img/integrations/integrations-tab.png) +![The Integrations tab in Graph Manager](../img/integrations/integrations-tab.png) ### Daily reports -Daily reports from Engine are sent out around 9am in whichever timezone you configure them to be in. You turn them on in the "Integrations" tab as shown above. The reports have a set format that gives a birds-eye view of what your GraphQL API delivered in the previous day: +Daily reports from Graph Manager are sent out around 9am in whichever timezone you configure them to be in. You turn them on in the "Integrations" tab as shown above. The reports have a set format that gives a birds-eye view of what your GraphQL API delivered in the previous day: -![Engine slack report](../img/integrations/slack-report.png) +![Graph Manager slack report](../img/integrations/slack-report.png) #### Using the report @@ -105,7 +105,7 @@ We've constructed the report provided to give you an actionable summary of what' ### Notifications -In Engine you can configure notifications that are triggered on the performance data of your graph, like error percentages and request latencies. This is particularly useful for detecting anomalies, especially around releases. Notifications can be configured to monitor the following metrics for either your entire GraphQL service or individual operations: +In Graph Manager, you can configure notifications that are triggered on the performance data of your graph, like error percentages and request latencies. This is particularly useful for detecting anomalies, especially around releases. Notifications can be configured to monitor the following metrics for either your entire GraphQL service or individual operations: - **Request rate:**  requests per minute - **Request duration:** p50/p95/p99 service time @@ -119,14 +119,14 @@ The triggers you set up are evaluated on a rolling five minute window. For examp ## Datadog -The Apollo Datadog integration allows you to forward all the performance metrics and analytics data that's available to you in Engine to Datadog as well. This is particularly convenient for teams already relying on Datadog for their monitoring, and of the best perks is that Datadog has advanced filtering features that alerts can be set on, and teams can set those alerts based on their GraphQL metrics data from Engine through Datadog. +The Apollo Datadog integration allows you to forward all the performance metrics and analytics data that's available to you in Graph Manager to Datadog as well. This is particularly convenient for teams already relying on Datadog for their monitoring, and of the best perks is that Datadog has advanced filtering features that alerts can be set on, and teams can set those alerts based on their GraphQL metrics data from Graph Manager through Datadog. -The Datadog metrics forwarded by Engine are: +The Datadog metrics forwarded by Graph Manager are: - `apollo.engine.operations.count`: the number of GraphQL operations that were executed. This includes queries, mutations, and operations that resulted in an error. -- `apollo.engine.operations.error_count`: the number of GraphQL operations that resulted in an error. This includes GraphQL execution errors, and HTTP errors if Engine failed to connect to your server. -- `apollo.engine.operations.cache_hit_count`: the number of GraphQL queries whose result was served from Apollo Engine's full query cache. -- A histogram of GraphQL operation response times, measured in milliseconds. Due to Engine's aggregation method (logarithmic binning), these values are accurate to +/- 5%: +- `apollo.engine.operations.error_count`: the number of GraphQL operations that resulted in an error. This includes GraphQL execution errors, and HTTP errors if Graph Manager failed to connect to your server. +- `apollo.engine.operations.cache_hit_count`: the number of GraphQL queries whose result was served from Apollo Graph Manager's full query cache. +- A histogram of GraphQL operation response times, measured in milliseconds. Due to Graph Manager's aggregation method (logarithmic binning), these values are accurate to +/- 5%: - `apollo.engine.operations.latency.min` - `apollo.engine.operations.latency.median` - `apollo.engine.operations.latency.95percentile` @@ -134,16 +134,16 @@ The Datadog metrics forwarded by Engine are: - `apollo.engine.operations.latency.max` - `apollo.engine.operations.latency.avg` -All of Engine's new Datadog metrics are tagged with the GraphQL operation name, as `operation:`. Unique query signatures with the same operation name are merged, and queries without an operation name are ignored. -All of the metrics are also tagged with the Engine graph ID, `service:`, so multiple graphs from Engine can send data to the same Datadog account. +All of Graph Manager's new Datadog metrics are tagged with the GraphQL operation name, as `operation:`. Unique query signatures with the same operation name are merged, and queries without an operation name are ignored. +All of the metrics are also tagged with the Graph Manager graph ID, `service:`, so multiple graphs from Graph Manager can send data to the same Datadog account. -Engine sends metrics to Datadog in 60 second intervals. Data is forwarded with a 60 second delay to allow for reports to be collected, even in the case of temporary network failures. +Graph Manager sends metrics to Datadog in 60-second intervals. Data is forwarded with a 60-second delay to allow for reports to be collected, even in the case of temporary network failures. -If you're reporting metrics to Engine through the Engine proxy, Datadog will merge you statistics across multiple instances of the proxy (per-host metrics are not available). Just like in the Engine UI, each operation inside a query batch is counted individually. +If you're reporting metrics to Graph Manager through the Engine proxy, Datadog will merge your statistics across multiple instances of the proxy (per-host metrics are not available). Just like in the Graph Manager UI, each operation inside a query batch is counted individually. #### Setup -Getting set up with Engine's Datadog integration is as simple as providing a Datadog API key to Engine. There's no further configuration required! You will need to have an account with administrator access to Datadog to acquire that API key. +Getting set up with Graph Manager's Datadog integration is as simple as providing a Datadog API key to Graph Manager. There's no further configuration required! You will need to have an account with administrator access to Datadog to acquire that API key. 1. Go to The [Datadog integrations page](https://app.datadoghq.com/account/settings) and search for "Apollo Engine". 2. Click the "+Available" button and go the the _Configuration_ tab. Copy the API key from the "Configuration" tab, click "Install Integration" at the bottom, and go to the [service](https://engine.apollographql.com) you'd like to enable Datadog Metric Forwarding for. @@ -158,11 +158,11 @@ Get the API Key from the Configuration tab before clicking "Install Integration" ![ApiKey](../img/datadog/api-key.png) -Once you've turned on the integration in Datadog, visit the "Integrations" tab in your Engine account and turn on the toggle for Datadog. +Once you've turned on the integration in Datadog, visit the "Integrations" tab in your Graph Manager account and turn on the toggle for Datadog. #### Metrics exploration -Once you have Datadog forwarding set up, you will start seeing Engine metrics forwarded to your Datadog account within a few minutes. Navigate to the [Datadog metric explorer](http://app.datadoghq.com/metric/explorer?exp_metric=apollo.engine.operations.count&exp_group=service&exp_agg=avg&exp_row_type=metric) to see data from your GraphQL service flowing in. +Once you have Datadog forwarding set up, you will start seeing Graph Manager metrics forwarded to your Datadog account within a few minutes. Navigate to the [Datadog metric explorer](http://app.datadoghq.com/metric/explorer?exp_metric=apollo.engine.operations.count&exp_group=service&exp_agg=avg&exp_row_type=metric) to see data from your GraphQL service flowing in. Each of the metrics reported is [tagged](https://www.datadoghq.com/blog/the-power-of-tagged-metrics/) with the graph ID (`service:`) it is reporting for and the operation name (`operation:`), both of which are normalized by Datadog naming requirements (letters are all lower-case and illegal symbols are converted to underscores). This tagging makes it easier to see data at whatever level of granularity you might want. @@ -170,7 +170,7 @@ If you want to aggregate across all operations or zoom in to a particular operat **Example**: Suppose you want to see the 95th percentile averaged across all operations for a staging and a production service. -_In the metric explorer, select `apollo.engine.operations.latency.95percentile` and then choose service where it says “one graph per” and select the two services you'd like to compare. At Apollo, we monitor Engine with Engine on our production and staging environments, so this graph for us looks like the following_: +_In the metric explorer, select `apollo.engine.operations.latency.95percentile` and then choose service where it says “one graph per” and select the two services you'd like to compare. At Apollo, we use Graph Manager to monitor Graph Manager itself, so this graph for us looks like the following_: ![Compare p95](../img/datadog/datadog.png) @@ -178,7 +178,7 @@ _To perform more advanced manipulation of metrics, open up the [Metrics notebook #### Monitoring with Datadog -All of the metrics reported to Datadog can be notified on directly through Engine via the Notifications feature, but Datadog can be a powerful partner in enabling more complex alerts. +All of the metrics reported to Datadog can be notified on directly through Graph Manager via the Notifications feature, but Datadog can be a powerful partner in enabling more complex alerts. **Example**: Suppose you have a query that is run against your GraphQL server with a much higher volume in the morning than in the afternoon. You want to enable monitoring on that query's latency and error rates, but if the query volume is very low, you have a higher tolerance for latency and one error will skew the error rate and make the monitor too noisy. diff --git a/docs/source/platform/operation-registry.mdx b/docs/source/platform/operation-registry.mdx index 33e24a0..3fdfe90 100644 --- a/docs/source/platform/operation-registry.mdx +++ b/docs/source/platform/operation-registry.mdx @@ -3,7 +3,7 @@ title: Securing your graph description: How to secure your graph by enforcing a safelist of registered operations --- -import { ExpansionPanel } from "gatsby-theme-apollo-docs"; +import { ExpansionPanel } from 'gatsby-theme-apollo-docs'; ## Overview @@ -17,15 +17,15 @@ The Apollo Platform comes with an **operation registry** and **safelisting** mec - Permit the exact operations necessary for their client applications. - Eliminate the risk of unexpected, and possibly costly, operations being executed against their graph. -Operations defined within client applications can be extracted and uploaded to Apollo Engine using the Apollo CLI. Apollo Server then fetches a manifest of these operations from Apollo Engine and forbids the execution of any operations that were not in that manifest. +Operations defined within client applications can be extracted and uploaded to Apollo Graph Manager using the Apollo CLI. Apollo Server then fetches a manifest of these operations from Apollo Graph Manager and forbids the execution of any operations that were not in that manifest. ### Prerequisites - [Apollo Server 2.2.x](https://www.apollographql.com/docs/apollo-server/) (or newer). - To get started with Apollo Server, visit [its documentation](https://www.apollographql.com/docs/apollo-server/). - A client application which utilizes `gql` tagged template literals for its operations or, alternatively, stores operations in `.graphql` files. -- An Apollo Engine API key. - - To obtain an API key, visit [Apollo Engine](https://engine.apollographql.com) and create a service. You will need and Engine account with a Team or Enterprise subscription to be able to upload to the operation registry. +- An Apollo Graph Manager API key. + - To obtain an API key, visit [Apollo Graph Manager](https://engine.apollographql.com) and create a service. You will need a Graph Manager account with a Team or Enterprise subscription to be able to upload to the operation registry. ### Limitations @@ -37,8 +37,8 @@ Please [contact the Apollo sales team](https://www.apollographql.com/contact-sal Setting up operation registration and safelisting is a full-stack process, so you will need to have access to the client code containing the operations you want to register, and to the server within which you want to enforce the safelist. -- The **Apollo CLI** is used to search the client codebase for GraphQL operations and upload them to Apollo Engine. -- **Apollo Server** is then configured with a plugin which fetches the manifest from Apollo Engine and enforces safelisting using that manifest. +- The **Apollo CLI** is used to search the client codebase for GraphQL operations and upload them to Apollo Graph Manager. +- **Apollo Server** is then configured with a plugin which fetches the manifest from Apollo Graph Manager and enforces safelisting using that manifest. The following steps will walk through the steps necessary for both the client and server codebases. @@ -47,7 +47,7 @@ The following steps will walk through the steps necessary for both the client an 3. [Register operations from your client bundle](#3-register-operations-from-your-client-bundle) 4. [Disable subscription support on Apollo Server](#4-disable-subscription-support-on-apollo-server) 5. [Add the operation registry plugin to Apollo Server](#5-add-the-operation-registry-plugin-to-apollo-server) -6. [Start Apollo Server with Apollo Engine enabled](#6-start-apollo-server-with-apollo-engine-enabled) +6. [Start Apollo Server with Apollo Graph Manager enabled](#6-start-apollo-server-with-apollo-graph-manager-enabled) 7. [Verify](#7-verification) ### 1. Install the `apollo` command line tool @@ -64,7 +64,7 @@ npm install apollo --save-dev First, make sure Apollo Server is running and that introspection is enabled (it is often disabled in production). -Next, using the following command as a reference, replace the `` with the Apollo Engine API key from the appropriate service and specify the correct server endpoint with the `--endpoint` flag: +Next, using the following command as a reference, replace the `` with the Apollo Graph Manager API key from the appropriate service and specify the correct server endpoint with the `--endpoint` flag: ``` npx apollo service:push \ @@ -97,7 +97,7 @@ The `apollo client:push` command: - Accepts a list of files as a glob (e.g. `src/**/*.ts`) to search for GraphQL operations. - By default, includes the `__typename` fields which are added by Apollo Client at runtime. -To register operations, use the following command as a reference, taking care to replace the `` with the appropriate Apollo Engine API key, specifying a unique name for this application with ``, and indicating the correct glob of files to search: +To register operations, use the following command as a reference, taking care to replace the `` with the appropriate Apollo Graph Manager API key, specifying a unique name for this application with ``, and indicating the correct glob of files to search: ``` npx apollo client:push \ @@ -138,14 +138,14 @@ const server = new ApolloServer({ typeDefs, resolvers, // Ensure that subscriptions are disabled. - subscriptions: false + subscriptions: false, // ... }); ``` ### 5. Add the operation registry plugin to Apollo Server -Enable demand control by adding the operation registry to Apollo Server. To enable the operation registry within Apollo Server, it's necessary to install and enable the `apollo-server-plugin-operation-registry` plugin and ensure Apollo Server is configured to communicate with Apollo Engine. +Enable demand control by adding the operation registry to Apollo Server. To enable the operation registry within Apollo Server, it's necessary to install and enable the `apollo-server-plugin-operation-registry` plugin and ensure Apollo Server is configured to communicate with Apollo Graph Manager. First, add the appropriate plugin to the Apollo Server's `package.json`: @@ -166,10 +166,10 @@ const server = new ApolloServer({ // ... // New configuration plugins: [ - require("apollo-server-plugin-operation-registry")({ - forbidUnregisteredOperations: true - }) - ] + require('apollo-server-plugin-operation-registry')({ + forbidUnregisteredOperations: true, + }), + ], }); ``` @@ -221,18 +221,18 @@ Configure the `schemaTag` field to specify which tag to pull operation manifests const server = new ApolloServer({ // Existing configuration plugins: [ - require("apollo-server-plugin-operation-registry")({ - schemaTag: "overrideTag" // highlight-line - }) - ] + require('apollo-server-plugin-operation-registry')({ + schemaTag: 'overrideTag', // highlight-line + }), + ], }); ``` -### 6. Start Apollo Server with Apollo Engine enabled +### 6. Start Apollo Server with Apollo Graph Manager enabled -If the server was already configured to use Apollo Engine, no additional changes are necessary, but it's important to make sure that the server is configured to use the same service as the operations were registered with in step 3. +If the server was already configured to use Apollo Graph Manager, no additional changes are necessary, but it's important to make sure that the server is configured to use the same service as the operations were registered with in step 3. -If the server was not previously configured with Apollo Engine, be sure to start the server with the `ENGINE_API_KEY` variable set to the appropriate API key. For example: +If the server was not previously configured with Apollo Graph Manager, be sure to start the server with the `ENGINE_API_KEY` variable set to the appropriate API key. For example: ``` ENGINE_API_KEY= npm start @@ -243,12 +243,12 @@ Alternatively, the API key can be specified with the `engine` parameter on the A ```js const server = new ApolloServer({ // ... - engine: "" // highlight-line + engine: '', // highlight-line // ... }); ``` -> **Note:** For security, it's recommended to pass the Engine API key as an environment variable so it will not be checked into version control (VCS). +> **Note:** For security, it's recommended to pass the Graph Manager API key as an environment variable so it will not be checked into version control (VCS). ### 7. Verification @@ -290,28 +290,28 @@ const server = new ApolloServer({ typeDefs, resolvers, subscriptions: false, - engine: "", + engine: '', plugins: [ - require("apollo-server-plugin-operation-registry")({ + require('apollo-server-plugin-operation-registry')({ // De-structure the object to get the HTTP `headers` and the GraphQL // request `context`. Additional validation is possible, but this // function must be synchronous. For more details, see the note below. forbidUnregisteredOperations({ context, // Destructure the shared request `context`. request: { - http: { headers } // Destructure the `headers` class. - } + http: { headers }, // Destructure the `headers` class. + }, }) { // If a magic header is in place, allow any unregistered operation. - if (headers.get("Let-me-pass") === "Pretty please?") { + if (headers.get('Let-me-pass') === 'Pretty please?') { return false; } // Enforce operation safelisting on all other users. return true; - } - }) - ] + }, + }), + ], }); ``` @@ -438,14 +438,14 @@ specific variant/tag, follow these steps: ```js const server = new ApolloServer({ plugins: [ - require("apollo-server-plugin-operation-registry")({ - schemaTag: "prod", // highlight-line + require('apollo-server-plugin-operation-registry')({ + schemaTag: 'prod', // highlight-line // suggested before enforcing the safelist debug: true, - dryRun: true - }) - ] + dryRun: true, + }), + ], }); ``` diff --git a/docs/source/platform/performance.md b/docs/source/platform/performance.md index a57bc1e..90f51a1 100644 --- a/docs/source/platform/performance.md +++ b/docs/source/platform/performance.md @@ -9,35 +9,35 @@ From that information it is possible to track down slow or frequently erroring r #### How it works -With [one line of configuration](/references/setup-analytics/), Apollo Server will start recording traces of every request it receives and sending summaries of that performance data to Engine. Engine aggregates and summarizes those traces to provide segmented, filterable insights about your graph's usage. +With [one line of configuration](/references/setup-analytics/), Apollo Server will start recording traces of every request it receives and sending summaries of that performance data to Graph Manager. Graph Manager aggregates and summarizes those traces to provide segmented, filterable insights about your graph's usage. ## Traces -With the metrics reporting set up, you'll be able to see traces of your operations in [Engine](https://engine.apollographql.com). Execution of a GraphQL request happens layer by layer, and each field in the query calls a function in your server called a resolver. The [_trace_ view in Engine](https://blog.apollographql.com/the-new-trace-view-in-apollo-engine-566b25bdfdb0) allows you to look at a detailed breakdown of the execution for individual operations, with timing shown for every resolver. +With the metrics reporting set up, you'll be able to see traces of your operations in [Graph Manager](https://engine.apollographql.com). Execution of a GraphQL request happens layer by layer, and each field in the query calls a function in your server called a resolver. The [_trace_ view in Graph Manager](https://blog.apollographql.com/the-new-trace-view-in-apollo-engine-566b25bdfdb0) allows you to look at a detailed breakdown of the execution for individual operations, with timing shown for every resolver. ![Trace view](../img/trace.png) ### Critical path -When a trace is opened, some resolvers are collapsed and others are expanded. This is Engine automatically expanding resolvers on the "critical path" of the query. The critical path is the set of fields and resolvers that makes the longest sequence in the query. If you are trying to speed up your query's execution, this is the set of fields you should be looking at first. +When a trace is opened, some resolvers are collapsed and others are expanded. This is Graph Manager automatically expanding resolvers on the "critical path" of the query. The critical path is the set of fields and resolvers that makes the longest sequence in the query. If you are trying to speed up your query's execution, this is the set of fields you should be looking at first. ### Trace inspector -Every trace stored in Engine records the request's resolver timings, variables, and HTTP headers. This is particularly useful when debugging and the detailed information about the trace can be found by opening up the _trace inspector_: +Every trace stored in Graph Manager records the request's resolver timings, variables, and HTTP headers. This is particularly useful when debugging and the detailed information about the trace can be found by opening up the _trace inspector_: ![Trace Inspector](../img/trace-inspector.png) ### A note on GraphQL subscriptions -Engine does not currently track statistics or traces for subscriptions. The proxy does, however, support the transparent pass-through of subscription requests and responses. +Graph Manager does not currently track statistics or traces for subscriptions. The proxy does, however, support the transparent pass-through of subscription requests and responses. ## Operation signatures -Engine groups operations that select the same fields together, treating different queries distinctly even if they share the same name. Not every query string can be taken as-is for grouping though, because some queries inline their variables. For these cases, Engine has a _signature_ algorithm to normalize inline variables so that queries of the same shape can still be grouped together. +Graph Manager groups operations that select the same fields together, treating different queries distinctly even if they share the same name. Not every query string can be taken as-is for grouping though, because some queries inline their variables. For these cases, Graph Manager has a _signature_ algorithm to normalize inline variables so that queries of the same shape can still be grouped together. ### Signature algorithm -The current signature algorithm performs the following transformations when generating a signature. (Future improvements to Engine will allow users to customize the signature algorithm.) +The current signature algorithm performs the following transformations when generating a signature. (Future improvements to Graph Manager will allow users to customize the signature algorithm.) - Input argument values are mapped according to the following rules: - `Variable`, `BooleanValue`, and `EnumValue` preserved @@ -78,16 +78,16 @@ See the reference implementation of [query signatures](https://github.com/apollo ### Signatures and sensitive data -The signature algorithm is primarily designed to make it possible to treat operations that differ only in trivial ways as the same operation. It also happens that removing the content of string literals appears to achieve greater data privacy within Engine, but this is not the primary goal. In fact, Engine also sends the full raw query along with traces (though it does not currently expose them in the user interface), so relying on the signature to ensure sensitive data never hits Engine's servers is inappropriate. +The signature algorithm is primarily designed to make it possible to treat operations that differ only in trivial ways as the same operation. It also happens that removing the content of string literals appears to achieve greater data privacy within Graph Manager, but this is not the primary goal. In fact, Graph Manager also sends the full raw query along with traces (though it does not currently expose them in the user interface), so relying on the signature to ensure sensitive data never hits Graph Manager's servers is inappropriate. -Future versions of Engine are likely to change this default algorithm to leave string literals alone, though it will still be easy to configure your server to remove string literals like in the current implementation. We also intend to stop sending the full raw query in future versions of Engine, so that the signature algorithm really can be used to avoid sending sensitive data in queries to Engine. +Future versions of Graph Manager are likely to change this default algorithm to leave string literals alone, though it will still be easy to configure your server to remove string literals like in the current implementation. We also intend to stop sending the full raw query in future versions of Graph Manager, so that the signature algorithm really can be used to avoid sending sensitive data in queries to Graph Manager. -But where possible, we strongly advise that you keep sensitive data in GraphQL variables instead of in literal arguments in the query body, as you can more easily control which variables should be stripped out of the Engine reporting pathway for privacy purposes. See [data privacy](https://www.apollographql.com/docs/references/apollo-engine#data-privacy) for further detail on how this works. +But where possible, we strongly advise that you keep sensitive data in GraphQL variables instead of in literal arguments in the query body, as you can more easily control which variables should be stripped out of the Graph Manager reporting pathway for privacy purposes. See [data privacy](https://www.apollographql.com/docs/references/apollo-engine#data-privacy) for further detail on how this works. ## Error tracking -Metrics reporting to Engine comes with built-in error tracking for basic GraphQL errors. Engine will be able to classify errors by **error type**, **class**, and **message**. +Metrics reporting to Graph Manager comes with built-in error tracking for basic GraphQL errors. Graph Manager will be able to classify errors by **error type**, **class**, and **message**. ![Errors](../img/error.png) -The errors tab in Engine's metrics layer automatically shows errors aggregated across your service, and this can be filtered to errors for a specific operation using the filter panel. Each operation can have multiple requests that return errors and will list these. Each error listed that has one trace can have multiple errors under each resolver. Clicking into the trace for a request with errors will take you to details of that error instance. +The errors tab in Graph Manager's metrics layer automatically shows errors aggregated across your service, and this can be filtered to errors for a specific operation using the filter panel. Each operation can have multiple requests that return errors and will list these. Each error listed that has one trace can have multiple errors under each resolver. Clicking into the trace for a request with errors will take you to details of that error instance. diff --git a/docs/source/platform/schema-registry.mdx b/docs/source/platform/schema-registry.mdx index 933f9c0..dcd07e7 100644 --- a/docs/source/platform/schema-registry.mdx +++ b/docs/source/platform/schema-registry.mdx @@ -77,7 +77,7 @@ jobs: - run: sleep 5 # When running on the 'master' branch, push the latest version - # of the schema to Apollo Engine. + # of the schema to Apollo Graph Manager. - run: | if [ "${CIRCLE_BRANCH}" == "master" ]; then apollo service:push --tag=master @@ -86,9 +86,9 @@ jobs: ## Viewing schema change history -Changes made to your graph's schema over time can be viewed in [Engine](https://engine.apollographql.com) by browsing to the History page for your graph. Each time you push a new version of your schema, it will appear in your graph's history along with a list of the changes introduced in that version. +Changes made to your graph's schema over time can be viewed in [Graph Manager](https://engine.apollographql.com) by browsing to the History page for your graph. Each time you push a new version of your schema, it will appear in your graph's history along with a list of the changes introduced in that version. -![Schema history page in the Engine UI](../images/schema-history.png) +![Schema history page in the Graph Manager UI](../images/schema-history.png) ## Managing environments @@ -110,9 +110,9 @@ apollo service:push --tag=beta ### Associating metrics with a variant -There are a few ways to associate metrics reported to [Engine](https://engine.apollographql.com) with a specific variant: +There are a few ways to associate metrics reported to [Graph Manager](https://engine.apollographql.com) with a specific variant: -1. The best way to associate metrics with a variant of your graph is to start your server with an environment variable named `ENGINE_SCHEMA_TAG` that contains the name of your variant. This will link metrics sent to Engine with the value of that environment variable. +1. The best way to associate metrics with a variant of your graph is to start your server with an environment variable named `ENGINE_SCHEMA_TAG` that contains the name of your variant. This will link metrics sent to Graph Manager with the value of that environment variable. 1. Alternatively, add the `schemaTag` option to your Apollo Server configuration (works for Apollo Server 2.2+): ```js @@ -133,4 +133,4 @@ Keeping your schema up-to-date in Apollo's registry will ensure that you get the - The [Apollo VS Code extension](https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo) provides built-in linting on queries by validating against the schema in your registry. It also annotates fields with their descriptions and with performance indicators collected in Apollo's trace warehouse. - The [schema validation](/platform/schema-validation/) workflow protects your team from accidentally making breaking schema changes. It creates a diff between your local schema and the last schema pushed to the registry, and validates this diff against live traffic seen on your endpoint to warn you about problematic changes. -- Your schema's full history and current usage can be seen in [Apollo Engine](https://engine.apollographql.com). The History page tracks changes made over time, and the Explorer page shows which clients and which queries are using each field in your schema. +- Your schema's full history and current usage can be seen in [Apollo Graph Manager](https://engine.apollographql.com). The History page tracks changes made over time, and the Explorer page shows which clients and which queries are using each field in your schema. diff --git a/docs/source/platform/schema-validation.mdx b/docs/source/platform/schema-validation.mdx index aab5547..7a6f87f 100644 --- a/docs/source/platform/schema-validation.mdx +++ b/docs/source/platform/schema-validation.mdx @@ -7,7 +7,7 @@ There are many types of schema changes that can be potentially breaking to clien Apollo provides a tool to protect for exactly this scenario called **schema validation**. -> **Note:** Schema validation is an Apollo Platform feature available on the [Team and Enterprise plans](https://www.apollographql.com/plans/) of [Apollo Engine](https://engine.apollographql.com). +> **Note:** Schema validation is an Apollo Platform feature available on the [Team and Enterprise plans](https://www.apollographql.com/plans/) of [Apollo Graph Manager](https://engine.apollographql.com). ## How it works @@ -15,12 +15,12 @@ Schema validation is run through the Apollo CLI by executing the `apollo service Here's how it works: -1. You run `apollo service:check` locally or in CI. The proposed schema is sent to Engine's schema registry. -1. Engine creates a diff between the local schema and the most recently published schema in the registry. -1. Engine fetches a list of all operations sent to your graph in the last day (time window is [configurable](#adjusting-validation-parameters)). -1. Engine walks through the schema diff change-by-change and compares against the operation list to see if the changes will affect the behavior of any operations. -1. Engine returns the schema diff and indicates any breaking changes found. -1. The CLI prints the output of this check with a link to view more details in the Engine UI. +1. You run `apollo service:check` locally or in CI. The proposed schema is sent to Graph Manager's schema registry. +1. Graph Manager creates a diff between the local schema and the most recently published schema in the registry. +1. Graph Manager fetches a list of all operations sent to your graph in the last day (time window is [configurable](#adjusting-validation-parameters)). +1. Graph Manager walks through the schema diff change-by-change and compares against the operation list to see if the changes will affect the behavior of any operations. +1. Graph Manager returns the schema diff and indicates any breaking changes found. +1. The CLI prints the output of this check with a link to view more details in the Graph Manager UI. ### Breaking change detection @@ -37,22 +37,28 @@ Each of these change types removes a schema element. If an element of your graph FIELD_REMOVED: Field used by at least one operation was removed
  • - TYPE_REMOVED: Type(scalar, object) used by at least one operation was removed + TYPE_REMOVED: Type(scalar, object) used by at least one + operation was removed
  • - ARG_REMOVED: Argument was removed from a field used by at least one operation + ARG_REMOVED: Argument was removed from a field used by at least + one operation
  • - TYPE_REMOVED_FROM_UNION: Type was removed from a union used by at least one operation + TYPE_REMOVED_FROM_UNION: Type was removed from a union used by + at least one operation
  • - INPUT_FIELD_REMOVED: Field removed from an input type referenced by an argument on a field used by at least one operation + INPUT_FIELD_REMOVED: Field removed from an input type + referenced by an argument on a field used by at least one operation
  • - VALUE_REMOVED_FROM_ENUM: A value removed from an enum used by at least one operation + VALUE_REMOVED_FROM_ENUM: A value removed from an enum used by + at least one operation
  • - TYPE_REMOVED_FROM_INTERFACE: An object removed from an interface used by at least one operation + TYPE_REMOVED_FROM_INTERFACE: An object removed from an + interface used by at least one operation
    • @@ -62,10 +68,12 @@ Each of these changes adds a required input to a schema element. If an operation
    • - REQUIRED_ARG_ADDED: Non-nullable argument added to field used by at least one operation + REQUIRED_ARG_ADDED: Non-nullable argument added to field used + by at least one operation
    • - NON_NULL_INPUT_FIELD_ADDED: Non-null field added to an input object used by at least one operation + NON_NULL_INPUT_FIELD_ADDED: Non-null field added to an input + object used by at least one operation
    @@ -77,16 +85,20 @@ Each of these changes updates an existing schema element. If an operation is act
    • - FIELD_CHANGED_TYPE: Field used by at least one operation changed return type + FIELD_CHANGED_TYPE: Field used by at least one operation + changed return type
    • - INPUT_FIELD_CHANGED_TYPE: Field in input object changed type and is referenced by argument on field used by at least one operation + INPUT_FIELD_CHANGED_TYPE: Field in input object changed type + and is referenced by argument on field used by at least one operation
    • - TYPE_CHANGED_KIND: Type used by at least one operation changed, ex: scalar to object or enum to union + TYPE_CHANGED_KIND: Type used by at least one operation changed, + ex: scalar to object or enum to union
    • - ARG_CHANGED_TYPE: Argument changed type on field used by at least one operation + ARG_CHANGED_TYPE: Argument changed type on field used by at + least one operation
    @@ -96,7 +108,8 @@ These changes update the default value for an argument. If an operation is using
    • - ARG_DEFAULT_VALUE_CHANGE: Default value added or changed for argument on a field used by at least one operation + ARG_DEFAULT_VALUE_CHANGE: Default value added or changed for + argument on a field used by at least one operation
    @@ -105,29 +118,65 @@ These changes update the default value for an argument. If an operation is using These are change types detected ny the `apollo service:check` command, but they are "safe" and will always be compatible with all exisitng client usage of the graph. They will not affect the behavior of any clients if deployed.
      -
    • Optional arguments +
    • + Optional arguments
        -
      • OPTIONAL_ARG_ADDED Nullable argument added to a field
        • -
      • NULLABLE_FIELD_ADDED_TO_INPUT_OBJECT Nullable field added to an input object
        • +
      • + OPTIONAL_ARG_ADDED Nullable argument added to a field +
        • +
      • + NULLABLE_FIELD_ADDED_TO_INPUT_OBJECT Nullable field added + to an input object +
      • -
    • Additions +
    • + Additions
        -
      • FIELD_ADDED Field added to a type
        • -
      • TYPE_ADDED Type added to the schema
        • -
      • VALUE_ADDED_TO_ENUM Value added to an enum. If clients contain a switch case on the enum and do not include the `default`, this change could cause unexpected behavior
        • -
      • TYPE_ADDED_TO_UNION Type added to a union used by at least one operation
        • -
      • TYPE_ADDED_TO_INTERFACE Interface added to an object used by at least one operation
        • +
      • + FIELD_ADDED Field added to a type +
        • +
      • + TYPE_ADDED Type added to the schema +
        • +
      • + VALUE_ADDED_TO_ENUM Value added to an enum. If clients + contain a switch case on the enum and do not include the `default`, this + change could cause unexpected behavior +
        • +
      • + TYPE_ADDED_TO_UNION Type added to a union used by at least + one operation +
        • +
      • + TYPE_ADDED_TO_INTERFACE Interface added to an object used + by at least one operation +
      • -
    • Deprecations +
    • + Deprecations
        -
      • FIELD_DEPRECATED Field deprecated
        • -
      • FIELD_DEPRECATION_REMOVED Field no longer deprecated
        • -
      • FIELD_DEPRECATED_REASON_CHANGE Reason for deprecation changed
        • -
      • ENUM_DEPRECATED Enum deprecated
        • -
      • ENUM_DEPRECATION_REMOVED Enum no longer deprecated
        • -
      • ENUM_DEPRECATED_REASON_CHANGE Reason for enum deprecation changed
        • +
      • + FIELD_DEPRECATED Field deprecated +
        • +
      • + FIELD_DEPRECATION_REMOVED Field no longer deprecated +
        • +
      • + FIELD_DEPRECATED_REASON_CHANGE Reason for deprecation + changed +
        • +
      • + ENUM_DEPRECATED Enum deprecated +
        • +
      • + ENUM_DEPRECATION_REMOVED Enum no longer deprecated +
        • +
      • + ENUM_DEPRECATED_REASON_CHANGE Reason for enum deprecation + changed +
    @@ -159,9 +208,9 @@ PASS TYPE_REMOVED `UploadPartialSchemaResponse` removed View full details at: https://engine.apollographql.com/service/example-1234/check/
    ``` -Each change to the schema will be labeled with `PASS` or `FAIL` and a URL with full details on the changes and their impact on clients and operations will be generated. Following the URL will take you to Engine: +Each change to the schema will be labeled with `PASS` or `FAIL` and a URL with full details on the changes and their impact on clients and operations will be generated. Following the URL will take you to Graph Manager: -![Service check page in the Engine UI](../img/schema-validation/service-check-page.png) +![Service check page in the Graph Manager UI](../img/schema-validation/service-check-page.png) > **Note:** If you have [installed schema validation checks on your GitHub PRs](#github-integration), the "Details" link in your GitHub checks will take you to the same details link in this output. @@ -173,7 +222,7 @@ Since breaking changes are detected using live traffic, your service will _need To set up schema validation, you will need to be both actively sending traces and registering schemas to Apollo: -1. [Set up trace reporting to Apollo Engine](/references/setup-analytics/) +1. [Set up trace reporting to Apollo Graph Manager](/references/setup-analytics/) 1. [Set up schema registration in your continuous delivery pipeline](/platform/schema-registry/) Then, you will need to configure your project for the `apollo service:check` command: @@ -193,7 +242,7 @@ $ npx apollo service:check The command can be placed in any continuous integration pipeline. To surface results, `apollo` emits an exit code and [integrates with GitHub statuses](#github-integration). The time window of live traffic that the check command validates against can be [configured](#adjusting-validation-parameters) to any range within your data retention window. -> **Note:** The Apollo CLI will be looking in your Apollo config for a location from which to fetch your local schema and using your ENGINE_API_KEY to authenticate its requests with the Engine service. +> **Note:** The Apollo CLI will be looking in your Apollo config for a location from which to fetch your local schema and using your ENGINE_API_KEY to authenticate its requests with the Graph Manager service. ### Run validation on each commit diff --git a/docs/source/references/apollo-config.md b/docs/source/references/apollo-config.md index 391a661..e24bb5a 100644 --- a/docs/source/references/apollo-config.md +++ b/docs/source/references/apollo-config.md @@ -35,12 +35,12 @@ There are a few different ways you can link your client to a schema: To link your client to a schema through the Apollo schema registry, you'll need to have at least one version of your schema uploaded to the [registry](/platform/schema-registry/). -With Engine set up, you can point your client directly to your graph's schema by putting your graph's Engine ID in your Apollo config, like so: +With Graph Manager set up, you can point your client directly to your graph's schema by putting your graph's Graph Manager ID in your Apollo config, like so: ```js{3} module.exports = { client: { - service: 'my-apollo-service' // the id of your service in Engine (from the URL) + service: 'my-apollo-service' // the id of your service in Graph Manager (from the URL) } }; ``` diff --git a/docs/source/references/setup-analytics.md b/docs/source/references/setup-analytics.md index ed1fb87..dbfde2a 100644 --- a/docs/source/references/setup-analytics.md +++ b/docs/source/references/setup-analytics.md @@ -11,11 +11,11 @@ A "trace" corresponds to exactly one [GraphQL operation](https://www.apollograph By recording which resolvers executed in our server and their traces, we can build a rich dataset. From it, we see exactly which query shapes are being run, who is sending them, which parts of the schema are most utilized, which resolvers in the server are bottlenecks, etc. -We've specifically built an interface to view this information into [Apollo Engine](https://engine.apollographql.com/) and any GraphQL server can report metrics to Engine by sending data in the `apollo-tracing` format to our metrics ingress. Read on to learn how to set this up in your environment. +We've specifically built an interface to view this information into [Apollo Graph Manager](https://engine.apollographql.com/) and any GraphQL server can report metrics to Engine by sending data in the `apollo-tracing` format to our metrics ingress. Read on to learn how to set this up in your environment. ## Apollo Server -Apollo Server has had the ability to report its performance usage metrics to Engine built-in. To set it up, get an API key from [Engine](https://engine.apollographql.com/) by logging in and creating a graph. Then set your API key in the `ENGINE_API_KEY` environment variable or pass it into your Apollo Server constructor like so: +Apollo Server has had the ability to report its performance usage metrics to Graph Manager built-in. To set it up, get an API key from [Graph Manager](https://engine.apollographql.com/) by logging in and creating a graph. Then set your API key in the `ENGINE_API_KEY` environment variable or pass it into your Apollo Server constructor like so: ```js{6-8} const { ApolloServer } = require("apollo-server"); @@ -42,9 +42,9 @@ There are 2 ways to send metrics data from your server to Engine: 1. Report traces directly from your server to our reporting endpoint 2. Use an Apollo tracing package and the Engine proxy (deprecated) -### Engine reporting endpoint +### Graph Manager reporting endpoint -We recommend following the agent pattern to report trace metrics from your server to the Engine reporting endpoint. This is what Apollo Server does internally and you can view the code for the [Apollo Server reference agent](https://github.com/apollographql/apollo-server/blob/3d6912434051ae7038153ef39e32f485a35609f0/packages/apollo-engine-reporting/src/agent.ts) as an example. +We recommend following the agent pattern to report trace metrics from your server to the Graph Manager reporting endpoint. This is what Apollo Server does internally and you can view the code for the [Apollo Server reference agent](https://github.com/apollographql/apollo-server/blob/3d6912434051ae7038153ef39e32f485a35609f0/packages/apollo-engine-reporting/src/agent.ts) as an example. We've been working with our community to build agent integrations for non-JavaScript servers. If you're interested in collaborating with us on an integration for your server, please get in touch with us at or via our [Apollo Spectrum Community](https://spectrum.chat/apollo). diff --git a/docs/source/resources/faq.md b/docs/source/resources/faq.md index d89c9c5..511957e 100644 --- a/docs/source/resources/faq.md +++ b/docs/source/resources/faq.md @@ -21,9 +21,9 @@ GraphQL can make a difference in nearly every area of development: from improvin There are a number of resources available to learn GraphQL. If you're looking to get started learning the basics, check out [GraphQL.org](https://graphql.org). -The simplest way to get started with implementing GraphQL is with the Apollo platform. The Apollo platform includes all the tools needed to get started, including a production-ready GraphQL server (`apollo-server`), a fully-featured schema management and monitoring tool, Apollo Engine, and a client that manages local and remote data in your apps (`apollo-client`). +The simplest way to get started with implementing GraphQL is with the Apollo platform. The Apollo platform includes all the tools needed to get started, including a production-ready GraphQL server (`apollo-server`), a fully-featured schema management and monitoring tool, Apollo Graph Manager, and a client that manages local and remote data in your apps (`apollo-client`). -To get started, read the getting started guides for [`apollo-server`](https://www.apollographql.com/docs/apollo-server/getting-started.html), [Apollo Engine](https://engine.apollographql.com), and [`react-apollo`](https://www.apollographql.com/docs/react/essentials/get-started.html) (the react integration for apollo-client). +To get started, read the getting started guides for [`apollo-server`](https://www.apollographql.com/docs/apollo-server/getting-started.html), [Apollo Graph Manager](https://engine.apollographql.com), and [`react-apollo`](https://www.apollographql.com/docs/react/essentials/get-started.html) (the react integration for apollo-client). This site and the [Apollo blog](https://blog.apollographql.com) are also great places to learn and keep up with the latest developments in GraphQL and Apollo. @@ -68,7 +68,7 @@ As with any service, it's important to track errors and their causes. There are GraphQL is resilient to some of these errors. Since the schema is strongly typed, the designer has the ability to restrict what type of data users can enter and what type the resolvers can return. This type system catches many errors and requires no manual checks. -For errors not prevented by the type system, it's helpful to know what exact queries were made, and with what variables. [Apollo Engine](https://www.apollographql.com/engine) is a tool that does exactly this. It can help discover and reproduce errors by showing the exact conditions in which the error occurred. +For errors not prevented by the type system, it's helpful to know what exact queries were made, and with what variables. [Apollo Graph Manager](https://www.apollographql.com/engine) is a tool that does exactly this. It can help discover and reproduce errors by showing the exact conditions in which the error occurred. ## Moving a feature to GraphQL @@ -106,9 +106,9 @@ Partial query caching can be achieved by caching the responses from underlying s Many apps and sites are powered almost completely by an API such as a GraphQL schema, so it's important to make sure the API is healthy at all times. Indicators of an unhealthy service include long response times, high resource usage, and unusual traffic patterns. -[Apollo Engine](https://www.apollographql.com/platform) is a great tool to track many of these things. It allows close inspection of fields to make it easy to see both total response times as well as how long each field took to execute. +[Apollo Graph Manager](https://www.apollographql.com/platform) is a great tool to track many of these things. It allows close inspection of fields to make it easy to see both total response times as well as how long each field took to execute. -Apollo Engine also has some integrations to make monitoring easier. The [Slack Integration](https://www.apollographql.com/docs/platform/integrations#slack) delivers daily reports to give teams a quick overview of the health of their schema. The [DataDog integration](https://www.apollographql.com/docs/platform/integrations#datadog)) works with existing DataDog accounts, to help teams track schema performance. +Apollo Graph Manager also has some integrations to make monitoring easier. The [Slack Integration](https://www.apollographql.com/docs/platform/integrations#slack) delivers daily reports to give teams a quick overview of the health of their schema. The [DataDog integration](https://www.apollographql.com/docs/platform/integrations#datadog)) works with existing DataDog accounts, to help teams track schema performance. ## Moving a product to GraphQL @@ -128,4 +128,4 @@ Keeping all schema code together makes sense for smaller projects, but once a pr Schemas naturally evolve over time. GraphQL schemas are more resilient to change than other APIs, but there are still occasions where breaking changes will need to happen to support new functionality. The [versioning guide](/platform/schema-registry/#registering-a-schema) explains in more detail what kinds of changes are safe to make, and what kinds could break existing clients. -Additionally, using the [Apollo CLI](https://www.npmjs.com/package/apollo) with Apollo Engine provides the tools needed to [validate schema changes](https://www.apollographql.com/docs/engine/features/schema-history.html) over time. This makes collaboration easier and more transparent. +Additionally, using the [Apollo CLI](https://www.npmjs.com/package/apollo) with Apollo Graph Manager provides the tools needed to [validate schema changes](https://www.apollographql.com/docs/engine/features/schema-history.html) over time. This makes collaboration easier and more transparent. diff --git a/docs/source/resources/graphql-glossary.md b/docs/source/resources/graphql-glossary.md index bae8704..2576e43 100644 --- a/docs/source/resources/graphql-glossary.md +++ b/docs/source/resources/graphql-glossary.md @@ -7,7 +7,7 @@ When you start diving into the GraphQL ecosystem, you'll probably encounter some ## Apollo -An open-source implementation of GraphQL that helps you manage data between the cloud and your UI. The Apollo platform is pluggable into your existing architecture and features production-ready tooling that helps you scale GraphQL across your organization ([Server](https://www.apollographql.com/docs/apollo-server/getting-started/), [Client](https://www.apollographql.com/docs/react/), and [Engine](https://www.apollographql.com/docs/engine/)). +An open-source implementation of GraphQL that helps you manage data between the cloud and your UI. The Apollo platform is pluggable into your existing architecture and features production-ready tooling that helps you scale GraphQL across your organization ([Server](https://www.apollographql.com/docs/apollo-server/getting-started/), [Client](https://www.apollographql.com/docs/react/), and [Graph Manager](https://www.apollographql.com/docs/engine/)). ## Automatic Persisted Queries (APQ) @@ -368,11 +368,11 @@ A [development approach](/intro/platform/#workflows) for designing and building ## Schema registry -A central source of truth for your schema in Apollo Engine. It enables schema registration, schema validation, tracking of detailed schema changes e.g. types added, fields added, fields deprecated and looking up previous versions of schema. +A central source of truth for your schema in Apollo Graph Manager. It enables schema registration, schema validation, tracking of detailed schema changes e.g. types added, fields added, fields deprecated and looking up previous versions of schema. ## Schema versioning -Refers to the need to evolve a schema over time. As a schema evolves, there is a potential for introducing breaking changes to clients. The Apollo CLI assists schema evolution by validating schema changes and checking for breaking changes using Apollo Engine. Read more in our article about [schema change validation](/platform/schema-validation/#set-up-schema-validation). +Refers to the need to evolve a schema over time. As a schema evolves, there is a potential for introducing breaking changes to clients. The Apollo CLI assists schema evolution by validating schema changes and checking for breaking changes using Apollo Graph Manager. Read more in our article about [schema change validation](/platform/schema-validation/#set-up-schema-validation). ## Schema stitching diff --git a/docs/source/tutorial/client.md b/docs/source/tutorial/client.md index bf71bf5..906e7cd 100644 --- a/docs/source/tutorial/client.md +++ b/docs/source/tutorial/client.md @@ -27,7 +27,7 @@ Now, our dependencies are installed. Here are the packages we will be using to b While Apollo VSCode is not required to successfully complete the tutorial, setting it up unlocks a lot of helpful features such as autocomplete for operations, jump to fragment definitions, and more. -First, make a copy of the `.env.example` file located in `client/` and call it `.env`. Add your Engine API key that you already created in step #4 to the file: +First, make a copy of the `.env.example` file located in `client/` and call it `.env`. Add your Graph Manager API key that you already created in step #4 to the file: ``` ENGINE_API_KEY=service:: diff --git a/docs/source/tutorial/introduction.md b/docs/source/tutorial/introduction.md index 3a0766a..29641d9 100644 --- a/docs/source/tutorial/introduction.md +++ b/docs/source/tutorial/introduction.md @@ -51,7 +51,7 @@ While it's not a requirement, we recommend using [VSCode](https://code.visualstu Now the fun begins! First, you'll need to install our developer tools: -- [Apollo Engine (required)](https://engine.apollographql.com) : Our cloud service where you'll register and manage your graph API. +- [Apollo Graph Manager (required)](https://engine.apollographql.com) : Our cloud service where you'll register and manage your graph API. - [Apollo DevTools for Chrome (suggested)](https://chrome.google.com/webstore/detail/apollo-client-developer-t/jdkknkkbebbapilgoeccciglkfbmbnfm) : Our Chrome extension giving you full visibility into your client. - [Apollo VSCode (suggested)](https://marketplace.visualstudio.com/items?itemName=apollographql.vscode-apollo): Our editor integration that offers intelligent autocomplete, metrics, and more. diff --git a/docs/source/tutorial/production.md b/docs/source/tutorial/production.md index 55e83ef..6441642 100644 --- a/docs/source/tutorial/production.md +++ b/docs/source/tutorial/production.md @@ -7,19 +7,19 @@ Time to accomplish: _15 Minutes_ Great job for making it this far! We've already learned how to build a GraphQL API with Apollo, connect it to REST and SQL data sources, and send GraphQL queries. Now that we've completed building our graph, it's finally time to deploy it! 🎉 -An Apollo GraphQL API can be deployed to any cloud service, such as Heroku, AWS Lambda, or Netlify. If you haven't already created an [Apollo Engine](https://engine.apollographql.com/) account, you will need to sign up for one. +An Apollo GraphQL API can be deployed to any cloud service, such as Heroku, AWS Lambda, or Netlify. If you haven't already created an [Apollo Graph Manager](https://engine.apollographql.com/) account, you will need to sign up for one. -## Publish your schema to Engine +## Publish your schema to Graph Manager -Before we deploy our app, we need to publish our schema to the Apollo Engine cloud service in order to power developer tooling like VSCode and keep track of schema changes. Just like npm is a registry for JavaScript packages, Apollo Engine contains a schema registry that makes it simple to pull the most recent schema from the cloud. +Before we deploy our app, we need to publish our schema to the Apollo Graph Manager cloud service in order to power developer tooling like VSCode and keep track of schema changes. Just like npm is a registry for JavaScript packages, Apollo Graph Manager contains a schema registry that makes it simple to pull the most recent schema from the cloud. -In a production application, you should set up this publishing script as part of your CI workflow. For now, we will run a script in our terminal that uses the Apollo CLI to publish our schema to Engine. +In a production application, you should set up this publishing script as part of your CI workflow. For now, we will run a script in our terminal that uses the Apollo CLI to publish our schema to Graph Manager. -### Get an Engine API key +### Get a Graph Manager API key -First, we need an Apollo Engine API key. Navigate to [Apollo Engine](https://engine.apollographql.com/), login, and click on _New Graph_ on the sidebar or at the top. The prompt will instruct you to name your graph. When you're finished, click _Create Graph_. You'll see a key appear prefixed by `service:`. Copy that key so we can save it as an environment variable. +First, we need an Apollo Graph Manager API key. Navigate to [Apollo Graph Manager](https://engine.apollographql.com/), login, and click on _New Graph_ on the sidebar or at the top. The prompt will instruct you to name your graph. When you're finished, click _Create Graph_. You'll see a key appear prefixed by `service:`. Copy that key so we can save it as an environment variable. -Let's save our key as an environment variable. It's important to make sure we don't check our Engine API key into version control. Go ahead and make a copy of the `.env.example` file located in `server/` and call it `.env`. Add your Engine API key that you copied from the previous step to the file: +Let's save our key as an environment variable. It's important to make sure we don't check our Graph Manager API key into version control. Go ahead and make a copy of the `.env.example` file located in `server/` and call it `.env`. Add your Graph Manager API key that you copied from the previous step to the file: ``` ENGINE_API_KEY=service:: @@ -35,7 +35,7 @@ Our key is now stored under the environment variable `ENGINE_API_KEY`. ### Check and publish with the Apollo CLI -It's time to publish our schema to Engine! First, start your server in one terminal window by running `npm start`. In another terminal window, run: +It's time to publish our schema to Graph Manager! First, start your server in one terminal window by running `npm start`. In another terminal window, run: ```bash npx apollo service:push --endpoint=http://localhost:4000 @@ -43,7 +43,7 @@ npx apollo service:push --endpoint=http://localhost:4000 > npx is a tool bundled with npm for easily running packages that are not installed globally. -This command publishes your schema to the Apollo registry. Once your schema is uploaded, you should be able to see your schema in the [Apollo Engine](https://engine.apollographql.com/) explorer. In future steps, we will pull down our schema from Engine in order to power the Apollo VSCode extension. +This command publishes your schema to the Apollo registry. Once your schema is uploaded, you should be able to see your schema in the [Apollo Graph Manager](https://engine.apollographql.com/) explorer. In future steps, we will pull down our schema from Graph Manager in order to power the Apollo VSCode extension. For subsequent publishes, we may first want to check for any breaking changes in our new schema against the old version. In a terminal window, run: @@ -51,12 +51,12 @@ For subsequent publishes, we may first want to check for any breaking changes in npx apollo service:check --endpoint=http://localhost:4000 ``` -### What are the benefits of Engine? +### What are the benefits of Graph Manager? -Publishing your schema to Apollo Engine unlocks many features necessary for running a graph API in production. Some of these features include: +Publishing your schema to Apollo Graph Manager unlocks many features necessary for running a graph API in production. Some of these features include: -- **Schema explorer:** With Engine's powerful schema registry, you can quickly explore all the types and fields in your schema with usage statistics on each field. This metric makes you understand the cost of a field. How expensive is a field? Is a certain field in so much demand? -- **Schema history:** Apollo Engine’s schema history allows developers to confidently iterate a graph's schema by validating the new schema against field-level usage data from the previous schema. This empowers developers to avoid breaking changes by providing insights into which clients will be broken by a new schema. +- **Schema explorer:** With Graph Manager's powerful schema registry, you can quickly explore all the types and fields in your schema with usage statistics on each field. This metric makes you understand the cost of a field. How expensive is a field? Is a certain field in so much demand? +- **Schema history:** Apollo Graph Manager schema history allows developers to confidently iterate a graph's schema by validating the new schema against field-level usage data from the previous schema. This empowers developers to avoid breaking changes by providing insights into which clients will be broken by a new schema. - **Performance analytics:** Fine-grained insights into every field, resolvers and operations of your graph's execution - **Client awareness:** Report client identity (name and version) to your server for insights on client activity.