From 0b1ef9a0ac7c973c64c89fb5e047032e55ff1289 Mon Sep 17 00:00:00 2001 From: Stephen Barlow Date: Fri, 2 Oct 2020 16:07:42 -0700 Subject: [PATCH] Replicate changes from glasser --- docs/source/entities.md | 2 +- docs/source/gateway.mdx | 2 +- docs/source/index.mdx | 4 ++-- docs/source/metrics.md | 12 ++++++------ docs/source/migrating-from-stitching.md | 16 +++++++--------- 5 files changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/source/entities.md b/docs/source/entities.md index 7ced21830..e83dfe413 100644 --- a/docs/source/entities.md +++ b/docs/source/entities.md @@ -217,7 +217,7 @@ Apollo Gateway helps you perform this migration much like you perform a database 3. Push the updated `inventory` service to your environment. - _Again, this technically deploys a composition error. **However**, this error is handled gracefully in one of two ways, depending on whether you are using [managed federation](https://www.apollographql.com/docs/graph-manager/federation/):_ + _Again, this technically deploys a composition error. **However**, this error is handled gracefully in one of two ways, depending on whether you are using [managed federation](https://www.apollographql.com/docs/studio/managed-federation/overview/):_ * _If you **are** using managed federation, Apollo Studio does **not** push an updated schema to your gateway, and the gateway continues to resolve the `inStock` field in the `products` service._ diff --git a/docs/source/gateway.mdx b/docs/source/gateway.mdx index 9413cb4f1..87de6a57e 100644 --- a/docs/source/gateway.mdx +++ b/docs/source/gateway.mdx @@ -54,7 +54,7 @@ In the above example, we provide the `serviceList` configuration option to the of our implementing services. You can specify any string value for `name`, which is used primarily for query planner output, error messages, and logging. -> In production, we recommend running the gateway in a **managed mode** with Apollo Studio, which relies on static files rather than introspection. For details, see [Setting up managed federation](https://www.apollographql.com/docs/graph-manager/managed-federation/setup/). +> In production, we recommend running the gateway in a **managed mode** with Apollo Studio, which relies on static files rather than introspection. For details, see [Setting up managed federation](https://www.apollographql.com/docs/studio/managed-federation/setup/). On startup, the gateway fetches each implementing service's schema from its `url` and composes those schemas into a single federated data graph. It then begins accepting incoming requests and creates query plans for them that execute across one or more services. diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 0c188f970..e7d1b6eee 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -166,9 +166,9 @@ operations across those implementing services. ### Managed federation -In addition to running a gateway with a static list of services, Apollo Gateway can operate in **managed federation** mode, where [Apollo Studio](https://www.apollographql.com/docs/graph-manager/) acts as the source of truth for each implementing service's schema. +In addition to running a gateway with a static list of services, Apollo Gateway can operate in **managed federation** mode, where [Apollo Studio](https://www.apollographql.com/docs/studio/) acts as the source of truth for each implementing service's schema. -This mode enables multiple teams working on a data graph to coordinate when and how underlying services change. For more information, read [Managed federation overview](https://www.apollographql.com/docs/graph-manager/managed-federation/overview/). +This mode enables multiple teams working on a data graph to coordinate when and how underlying services change. For more information, read [Managed federation overview](https://www.apollographql.com/docs/studio/managed-federation/overview/). ## Query example diff --git a/docs/source/metrics.md b/docs/source/metrics.md index 6888d89d9..8765a020d 100644 --- a/docs/source/metrics.md +++ b/docs/source/metrics.md @@ -3,20 +3,20 @@ title: Federated traces description: How federated tracing works --- -One of the many benefits of using GraphQL as an API layer is that it enables fine-grained [tracing](https://www.apollographql.com/docs/platform/performance/#traces) of every API call. One of the features of the Apollo platform is support for consuming and aggregating those traces in order to provide detailed insights into your GraphQL layer's performance and usage. In order to support this same functionality, the Federation model includes support for sending a federated trace from the Apollo gateway, which is constructed from timing and error information that underlying services expose. These federated traces capture the service-level details in the shape of the query plan, which is sent to Apollo's [metrics ingress](https://www.apollographql.com/docs/references/setup-analytics/#engine-reporting-endpoint) by default, and aggregated into query-level stats and field-level stats. The overall flow of a federated trace is as follows: +One of the many benefits of using GraphQL as an API layer is that it enables fine-grained [tracing](https://www.apollographql.com/docs/platform/performance/#traces) of every API call. One of the features of the Apollo platform is support for consuming and aggregating those traces in order to provide detailed insights into your GraphQL layer's performance and usage. In order to support this same functionality, the Federation model includes support for sending a federated trace from the Apollo gateway, which is constructed from timing and error information that underlying services expose. These federated traces capture the service-level details in the shape of the query plan, which is sent to Apollo's [metrics ingress](https://www.apollographql.com/docs/studio/setup-analytics/#sending-metrics-to-the-reporting-endpoint) by default, and aggregated into query-level stats and field-level stats. The overall flow of a federated trace is as follows: 1. The Apollo gateway receives an operation from a client 1. The Apollo gateway constructs a query plan for the operation, delegating sub-queries to underlying services 1. For each [fetch](https://www.apollographql.com/docs/federation/federation-spec/#fetch-service-capabilities) to an implementing service, a response is received 1. In the [`extensions`](https://www.apollographql.com/docs/resources/graphql-glossary/#extensions) of the response, a trace from the sub-query is exposed 1. The gateway collects the set of sub-query traces from implementing services, and arranges them in the shape of the [query plan](https://www.apollographql.com/docs/federation/implementing/#inspecting-query-plans) -1. The Federated trace is sent to the Apollo [metrics ingress](https://www.apollographql.com/docs/references/setup-analytics/#engine-reporting-endpoint) for processing. +1. The Federated trace is sent to the Apollo [metrics ingress](https://www.apollographql.com/docs/studio/setup-analytics/#sending-metrics-to-the-reporting-endpoint) for processing. The model of federated metrics is that implementing services report timing and error information to the gateway, and the gateway is responsible for reporting those metrics. ## Turning it on -Ensure that all dependencies on `apollo-server` are at version `2.7.0` or higher. Provide an API key to your gateway via the `APOLLO_KEY` environment variable for the gateway to report metrics to the default ingress. To ensure that implementing services do not report metrics as well, do not provide them with an `APOLLO_KEY` or set `{ engine: false }` in the constructor options to `ApolloServer`. +Ensure that all dependencies on `apollo-server` are at version `2.7.0` or higher. Provide an API key to your gateway via the `APOLLO_KEY` environment variable for the gateway to report metrics to the default ingress. To ensure that implementing services do not report metrics as well, do not provide them with an `APOLLO_KEY` or install the [`ApolloServerPluginUsageReportingDisabled` plugin](../api/plugin/usage-reporting/) in your `ApolloServer`. These options will cause the Apollo gateway to collect tracing information from the underlying federated services and pass them on, along with the query plan, to the Apollo metrics ingress. Currently, only Apollo Server supports detailed metrics insights as an implementing service, but we would love to work with you to implement the protocol in other languages! @@ -26,7 +26,7 @@ These options will cause the Apollo gateway to collect tracing information from > NOTE: this section details how the gateway communicates with federated services around encoded tracing information and is not necessary to understand in order to enable federated tracing. -The Apollo gateway looks to the `extensions` field of all service responses for the presence of an `ftv1` field. This field contains a representation of the tracing information for the sub-query that was executed against the service, sent as the Base64 encoding of the [protobuf representation](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-engine-reporting-protobuf/src/reports.proto) of the trace. In order to request this information of federated services, the gateway will send the header pair `'apollo-federation-include-trace': 'ftv1'` on fetches if configured to collect metrics, as per above. By default a federated Apollo Server service will recognize this header pair and attach tracing information in extensions of the response. +The Apollo gateway looks to the `extensions` field of all service responses for the presence of an `ftv1` field. This field contains a representation of the tracing information for the sub-query that was executed against the service, sent as the Base64 encoding of the [protobuf representation](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-reporting-protobuf/src/reports.proto) of the trace. In order to request this information of federated services, the gateway will send the header pair `'apollo-federation-include-trace': 'ftv1'` on fetches if configured to collect metrics, as per above. By default a federated Apollo Server service will recognize this header pair and attach tracing information in extensions of the response. ## How traces are constructed and aggregated @@ -34,8 +34,8 @@ The Apollo gateway constructs traces in the shape of the [query plan](https://ww ## How errors work -The Apollo Platform provides functionality to modify error details for the client, via the [`formatError`](https://www.apollographql.com/docs/apollo-server/features/errors/#for-the-client-response) option. Additionally, there is functionality to support modifying error details for the metrics ingress, via the [`rewriteError`](https://www.apollographql.com/docs/apollo-server/features/errors/#for-apollo-engine-reporting) option. +The Apollo Platform provides functionality to modify error details for the client, via the [`formatError`](https://www.apollographql.com/docs/apollo-server/features/errors/#for-the-client-response) option. Additionally, there is functionality to support modifying error details for the metrics ingress, via the [`rewriteError`](../data/errors/#for-apollo-studio-reporting) option to the [inline trace plugin](../api/plugin/inline-trace/). When modifying errors for the client, you might want to use this option to hide implementation details, like database errors, from your users. When modifying errors for reporting, you might want to obfuscate or redact personal information, like user IDs or emails. -Since federated metrics collection works by collecting latency and error information from a set of distributed implementing services, **these options are respected from underlying services** as well as from the gateway level. Federated services will embed errors in their `ftv1` extension after the `rewriteError` method is applied, and the gateway will only report the errors that are sent via that extension, ignoring the format that downstream errors are reported to end users. This functionality enable service-implementors to determine how error information should be displayed to both users and in metrics without needing the gateway to contain any logic that might be service-specific. +Since federated metrics collection works by collecting latency and error information from a set of distributed implementing services, **these options are respected from underlying services** as well as from the gateway level. Federated services will embed errors in their `ftv1` extension after the `rewriteError` method (passed to the inline trace plugin in the implementing service, not the usage reporting plugin in the gateway!) is applied, and the gateway will only report the errors that are sent via that extension, ignoring the format that downstream errors are reported to end users. This functionality enable service-implementors to determine how error information should be displayed to both users and in metrics without needing the gateway to contain any logic that might be service-specific. diff --git a/docs/source/migrating-from-stitching.md b/docs/source/migrating-from-stitching.md index 3613e8c37..115e80f88 100644 --- a/docs/source/migrating-from-stitching.md +++ b/docs/source/migrating-from-stitching.md @@ -72,13 +72,11 @@ There are [several community-contributed packages](/other-servers/) that add fed We strongly recommend that you register all of your GraphQL schemas with an [external registry](https://principledgraphql.com/integrity#3-track-the-schema-in-a-registry). This registry supports running the gateway with the implementing services' partial schemas. Additionally, it enables tracking changes at the service level and protecting the graph from changes that break composition. -[Apollo Studio](https://www.apollographql.com/docs/graph-manager/) provides a free schema registry that helps you manage your federated gateway's configuration. You provide your gateway a Studio API key on startup, which directs the gateway to download your schemas automatically in a fault-tolerant way. +[Apollo Studio](https://www.apollographql.com/docs/studio/) provides a free schema registry that helps you manage your federated gateway's configuration. You provide your gateway a Studio API key on startup, which directs the gateway to download your schemas automatically in a fault-tolerant way. -Studio can also provide [schema validation](https://www.apollographql.com/docs/graph-manager/federation/#validating-changes-to-the-graph) to ensure that all -changes you -make to your implementing services are compatible with your complete data graph. +Studio can also provide [schema validation](https://www.apollographql.com/docs/studio/managed-federation/overview/#validating-changes-to-the-graph) to ensure that all changes you make to your implementing services are compatible with your complete data graph. -> [Learn more about managed configuration](https://www.apollographql.com/docs/graph-manager/federation/#registering-federated-services) +> [Learn more about managed configuration](https://www.apollographql.com/docs/studio/managed-federation/overview/) ## Step 3: Start up an Apollo Server gateway @@ -86,7 +84,7 @@ After you've registered your schemas, you can start exposing your implementing s We recommend setting up the Apollo Server gateway _alongside_ your existing schema-stitching gateway. Depending on your infrastructure, you might even want to run both in the same _process_ to support dynamically routing traffic through one gateway or the other. -To enable managed configuration with Apollo Studio, set the `APOLLO_KEY` and `APOLLO_GRAPH_VARIANT` environment variables when you start up your Apollo Server gateway, and **do not provide the `serviceList` constructor option to `ApolloGateway`**. For details, see the [Apollo Studio documentation](https://www.apollographql.com/docs/graph-manager/managed-federation/setup/). +To enable managed configuration with Apollo Studio, set the `APOLLO_KEY` and `APOLLO_GRAPH_VARIANT` environment variables when you start up your Apollo Server gateway, and **do not provide the `serviceList` constructor option to `ApolloGateway`**. For details, see the [Apollo Studio documentation](https://www.apollographql.com/docs/studio/managed-federation/setup/). After your gateway is set up, you can make direct queries to it that are routed to the correct implementing services. @@ -194,6 +192,6 @@ You can now begin to modify your existing schema to take full advantage of the features that federation provides. These features include: * Greater flexibility with [federation core concepts](https://www.apollographql.com/docs/federation/core-concepts/) -* [Metrics and analysis of query plans](https://www.apollographql.com/docs/graph-manager/federation/#metrics-and-observability) -* [Gateway support for live schema updates from implementing services](https://www.apollographql.com/docs/graph-manager/federation/#diving-into-servicepush) -* [Validation of composition logic and usage traffic](https://www.apollographql.com/docs/graph-manager/federation/#validating-changes-to-the-graph) (with paid subscription) +* [Metrics and analysis of query plans](https://www.apollographql.com/docs/studio/managed-federation/advanced-topics/#metrics-and-observability) +* [Gateway support for live schema updates from implementing services](https://www.apollographql.com/docs/studio/managed-federation/advanced-topics/#diving-into-servicepush) +* [Validation of composition logic and usage traffic](https://www.apollographql.com/docs/studio/managed-federation/advanced-topics/#checking-changes-to-a-federated-graph) (with paid subscription)