diff --git a/docs/source/routing/observability/client-awareness.mdx b/docs/source/routing/observability/client-awareness.mdx deleted file mode 100644 index 8b5f566aef..0000000000 --- a/docs/source/routing/observability/client-awareness.mdx +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Client Awareness -subtitle: Configure client awareness in the router -description: Configure client awareness in the Apollo GraphOS Router or Apollo Router Core to separate the metrics and operations per client. ---- - -import { Link } from "gatsby"; - -The GraphOS Router and Apollo Router Core support [client awareness](/graphos/metrics/client-awareness/) by default. If the client sets the headers `apollographql-client-name` and `apollographql-client-version` in its HTTP requests, GraphOS Studio can separate the metrics and operations per client. - -This client name is also used by the [Persisted Queries](/graphos/routing/security/persisted-queries) feature. - -## Overriding client awareness headers - -Different header names can be used by updating the configuration file. If those headers will be sent by a browser, they must be allowed in the [CORS (Cross Origin Resource Sharing) configuration](/router/configuration/cors), as follows: - -```yaml title="router.yaml" -telemetry: - apollo: - # defaults to apollographql-client-name - client_name_header: MyClientHeaderName - # defaults to apollographql-client-version - client_version_header: MyClientHeaderVersion -cors: - # The headers to allow. - # (Defaults to [ Content-Type ], which is required for GraphOS Studio) - allow_headers: [ Content-Type, MyClientHeaderName, MyClientHeaderVersion] -``` diff --git a/docs/source/routing/observability/client-id-enforcement.mdx b/docs/source/routing/observability/client-id-enforcement.mdx index 474405547e..15d63fc691 100644 --- a/docs/source/routing/observability/client-id-enforcement.mdx +++ b/docs/source/routing/observability/client-id-enforcement.mdx @@ -1,5 +1,5 @@ --- -title: Client ID Enforcement +title: Client Awareness and Enforcement subtitle: Require client details and operation names to help monitor schema usage description: Improve GraphQL operation monitoring by tagging operations with with client details. See code examples for Apollo GraphOS Router and Apollo Server. published: 2022-05-31 @@ -7,19 +7,61 @@ id: TN0001 tags: [server, observability, router] redirectFrom: - /technotes/TN0001-client-id-enforcement/ + - /graphos/routing/observability/client-awareness --- -As part of GraphOS Studio metrics reporting, servers can [tag reported operations with the requesting client's name and version](/graphos/metrics/client-awareness). This helps graph maintainers understand which clients are using which fields in the schema. +Metrics about GraphQL schema usage are more insightful when information about clients using the schema is available. Understanding client usage can help you reshape your schema to serve clients more efficiently. +As part of GraphOS Studio metrics reporting, servers can [tag reported operations with the requesting client's name and version](/graphos/metrics/client-awareness). +This **client awareness** helps graph maintainers understand which clients are using which fields in the schema. -Clients can (and should) also [name their GraphQL operations](/react/data/operation-best-practices/#name-all-operations), which provides more context around how and where data is being used. +Apollo's GraphOS Router and Apollo Server can enable client awareness by requiring metadata about requesting clients. +The router supports client awareness by default. If the client sets its name and version with the headers `apollographql-client-name` and `apollographql-client-version` in its HTTP requests, GraphOS Studio can separate the metrics and operations per client. -Together, these pieces of information help teams monitor their graph and make changes to it safely. We strongly encourage that your GraphQL gateway require client details and operation names from all requesting clients. + + +The client name is also used by the persisted queries feature. + + + + +Clients should [name their GraphQL operations](/react/data/operation-best-practices/#name-all-operations) to provide more context around how and where data is being used. + +## Why enforce client reporting? + +Client metadata enables better insights into schema usage, such as: + +- **Identifying which clients use which fields**: This facilitates usage monitoring and safe deprecation of fields. +- **Understanding traffic patterns**: This helps optimize schema design based on real-world client behavior. +- **Improving operation-level observability**: This provides details for debugging and performance improvements. + +Apollo strongly recommends requiring client name, client version, and operation names in all incoming GraphQL requests. ## Enforcing in GraphOS Router -The GraphOS Router supports client awareness by default if the client sets the `apollographql-client-name` and `apollographql-client-id` in their requests. These values can be overridden using the [router configuration file](/router/managed-federation/client-awareness/) directly. +The GraphOS Router supports client awareness by default if the client sets the `apollographql-client-name` and `apollographql-client-id` in their requests. +These values can be overridden using the [router configuration file](/router/managed-federation/client-awareness/) directly. +You can use a Rhai script to _enforce_ that clients include metadata. + +### Customizing client awareness headers + +If headers with customized names need to be sent by a browser, they must be allowed in the [CORS (Cross Origin Resource Sharing) configuration](/router/configuration/cors), as follows: + +```yaml title="router.yaml" +telemetry: + apollo: + # defaults to apollographql-client-name + client_name_header: MyClientHeaderName + # defaults to apollographql-client-version + client_version_header: MyClientHeaderVersion +cors: + # The headers to allow. + # (Defaults to [ Content-Type ], which is required for GraphOS Studio) + allow_headers: [ Content-Type, MyClientHeaderName, MyClientHeaderVersion] +``` + +### Enforcing via Rhai script -Client headers can also be enforced using a [Rhai script](/graphos/routing/customization/rhai) on every incoming request. +Client headers can be enforced using a [Rhai script](/graphos/routing/customization/rhai) on every incoming request. ```rhai title="client-id.rhai" fn supergraph_service(service) {