From 7727ea57e10591d01e03a891fcaf1cc57acef667 Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Thu, 2 Jan 2025 13:34:29 -0800 Subject: [PATCH 1/7] Create debugging-client-requests.mdx --- .../debugging-client-requests.mdx | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/source/routing/observability/debugging-client-requests.mdx diff --git a/docs/source/routing/observability/debugging-client-requests.mdx b/docs/source/routing/observability/debugging-client-requests.mdx new file mode 100644 index 0000000000..5eea655e79 --- /dev/null +++ b/docs/source/routing/observability/debugging-client-requests.mdx @@ -0,0 +1,52 @@ +--- +title: Debugging Client Requests to GraphOS Router +subtitle: Log incoming requests to help debug problematic queries or errors +description: Enable telemetry features to help gain more visibility into incoming HTTP requests and help debug issues your clients may be having. +--- + +GraphOS Router by default does not emit access logs for the incoming client HTTP requests, nor are other features, like OpenTelemetry, on by default that include every request. Given the volume and size of GraphQL requests, this would produce a large amount of telemetry data that may impact your observability costs. + +The best way to see GraphQL operation data is to use [GraphOS Insights](https://www.apollographql.com/docs/graphos/platform/insights). Here you will be able to see failed requests, what the client id was, and what was the exact GraphQL error if enabled. + +If however, you are having issues with some requests coming from clients and would like to enable debugging features in your own evnironment, we reccomend first doing this in a non-production environment or using logic to do this on a per-request basis. + +## OpenTelemetry Spans and Traces +Using [Router Telemetry](https://www.apollographql.com/docs/graphos/routing/observability/telemetry), the trace for a give request will have a span labeled as `router`. This span will contain the HTTP information for a given client request with our [standard attributes](https://www.apollographql.com/docs/graphos/reference/router/telemetry/instrumentation/standard-attributes#router). + +This will include helpful information about the request and response, but you will notice that an attribute for the HTTP body text is not included. If you would like to see the GraphQL operation first check your [GraphOS Insights](https://www.apollographql.com/docs/graphos/platform/insights) or follow the other options listed below. + +## Request/Response Logging +Using either the [logging-when-header](https://www.apollographql.com/docs/graphos/reference/router/telemetry/log-exporters/overview#requestresponse-logging) feature you can include the request body in your logs conditionally. + +```yaml title="router.yaml" +telemetry: + exporters: + logging: + # If one of these headers matches we will log supergraph and subgraphs requests/responses + experimental_when_header: + - name: apollo-router-log-request + value: my_client + headers: true # default: false + body: true # default: false +``` + +## Rhai Scripts & Coprocessors + + +## Debug Router Logs +GraphOS Router by default uses the `info` level for its logging. [Enabling other logging levels](https://www.apollographql.com/docs/graphos/reference/router/telemetry/log-exporters/overview) can help debug specific scenarios. It is only reccomended for local or non-production environments. + +## Alternative Cloud Services +If you are deploying GraphOS Router to a cloud service, it is likely that you already have access to the raw HTTP logs through other services such as a load balancer. Using the trace id or operation hash, you should be able to find a specific client request to logs for that operation. Check out the docs for popular cloud providers here: + +AWS +* [AWS CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) +* [AWS Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-access-logs.html) + +GCP +* [Google Cloud Observability](https://cloud.google.com/logging/docs/log-analytics) +* [Google Cloud Load Balancing](https://cloud.google.com/load-balancing/docs/l7-internal/monitoring) + +Azure +* [Azure App Service Logging](https://learn.microsoft.com/en-us/azure/app-service/troubleshoot-diagnostic-logs) +* [Azure Load Balancer](https://learn.microsoft.com/en-us/azure/load-balancer/monitor-load-balancer] From d431547b91dca8aea8ba0bfd59081e1ef3f1ccef Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Thu, 2 Jan 2025 13:44:35 -0800 Subject: [PATCH 2/7] Create debug-client-requests.md --- .changesets/debug-client-requests.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changesets/debug-client-requests.md diff --git a/.changesets/debug-client-requests.md b/.changesets/debug-client-requests.md new file mode 100644 index 0000000000..fdcb76fb58 --- /dev/null +++ b/.changesets/debug-client-requests.md @@ -0,0 +1,5 @@ +### [docs] Create debugging-client-requests.mdx ([PR #6504](https://github.com/apollographql/router/pull/6504)) + +Add a docs page about how to debug client requests. This infomation is spread across many different features so this serves as a landing page for all of that. + +By [@smyrick](https://github.com/smyrick) in https://github.com/apollographql/router/pull/6504 From e592d8f083a0aa0c6fa3197105739e9878440af5 Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Thu, 2 Jan 2025 13:46:26 -0800 Subject: [PATCH 3/7] Rename debug-client-requests.md to docs_debug_client_requests.md --- .../{debug-client-requests.md => docs_debug_client_requests.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .changesets/{debug-client-requests.md => docs_debug_client_requests.md} (100%) diff --git a/.changesets/debug-client-requests.md b/.changesets/docs_debug_client_requests.md similarity index 100% rename from .changesets/debug-client-requests.md rename to .changesets/docs_debug_client_requests.md From 4f0cee45a64dc15d8b24cbafc36e0a2b69e91b72 Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Thu, 2 Jan 2025 14:12:44 -0800 Subject: [PATCH 4/7] Update debugging-client-requests.mdx --- docs/source/routing/observability/debugging-client-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/routing/observability/debugging-client-requests.mdx b/docs/source/routing/observability/debugging-client-requests.mdx index 5eea655e79..4f87b93287 100644 --- a/docs/source/routing/observability/debugging-client-requests.mdx +++ b/docs/source/routing/observability/debugging-client-requests.mdx @@ -4,7 +4,7 @@ subtitle: Log incoming requests to help debug problematic queries or errors description: Enable telemetry features to help gain more visibility into incoming HTTP requests and help debug issues your clients may be having. --- -GraphOS Router by default does not emit access logs for the incoming client HTTP requests, nor are other features, like OpenTelemetry, on by default that include every request. Given the volume and size of GraphQL requests, this would produce a large amount of telemetry data that may impact your observability costs. +By default, the GraphOS Router does not generate access logs for incoming client HTTP requests, nor are features like OpenTelemetry enabled to capture every request. The best way to see GraphQL operation data is to use [GraphOS Insights](https://www.apollographql.com/docs/graphos/platform/insights). Here you will be able to see failed requests, what the client id was, and what was the exact GraphQL error if enabled. From 8d641f877132c668cf55ad3de2bda70842e37a56 Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Thu, 2 Jan 2025 14:13:46 -0800 Subject: [PATCH 5/7] Update debugging-client-requests.mdx --- .../routing/observability/debugging-client-requests.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/routing/observability/debugging-client-requests.mdx b/docs/source/routing/observability/debugging-client-requests.mdx index 4f87b93287..fb7d467873 100644 --- a/docs/source/routing/observability/debugging-client-requests.mdx +++ b/docs/source/routing/observability/debugging-client-requests.mdx @@ -6,7 +6,7 @@ description: Enable telemetry features to help gain more visibility into incomin By default, the GraphOS Router does not generate access logs for incoming client HTTP requests, nor are features like OpenTelemetry enabled to capture every request. -The best way to see GraphQL operation data is to use [GraphOS Insights](https://www.apollographql.com/docs/graphos/platform/insights). Here you will be able to see failed requests, what the client id was, and what was the exact GraphQL error if enabled. +The best way to see GraphQL operation data is to use [GraphOS Insights](https://www.apollographql.com/docs/graphos/platform/insights). Here you will be able to see failed requests, what the client id was, and what was the exact [GraphQL error if enabled](https://www.apollographql.com/docs/graphos/routing/graphos-reporting#errors). If however, you are having issues with some requests coming from clients and would like to enable debugging features in your own evnironment, we reccomend first doing this in a non-production environment or using logic to do this on a per-request basis. @@ -16,7 +16,7 @@ Using [Router Telemetry](https://www.apollographql.com/docs/graphos/routing/obse This will include helpful information about the request and response, but you will notice that an attribute for the HTTP body text is not included. If you would like to see the GraphQL operation first check your [GraphOS Insights](https://www.apollographql.com/docs/graphos/platform/insights) or follow the other options listed below. ## Request/Response Logging -Using either the [logging-when-header](https://www.apollographql.com/docs/graphos/reference/router/telemetry/log-exporters/overview#requestresponse-logging) feature you can include the request body in your logs conditionally. +Using the [logging-when-header](https://www.apollographql.com/docs/graphos/reference/router/telemetry/log-exporters/overview#requestresponse-logging) feature you can include the request body in your logs conditionally. ```yaml title="router.yaml" telemetry: From 935efb4575fa4a2e2930d56d3afd502cc884a302 Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Thu, 2 Jan 2025 14:16:17 -0800 Subject: [PATCH 6/7] Update debugging-client-requests.mdx --- docs/source/routing/observability/debugging-client-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/routing/observability/debugging-client-requests.mdx b/docs/source/routing/observability/debugging-client-requests.mdx index fb7d467873..115fc83213 100644 --- a/docs/source/routing/observability/debugging-client-requests.mdx +++ b/docs/source/routing/observability/debugging-client-requests.mdx @@ -31,7 +31,7 @@ telemetry: ``` ## Rhai Scripts & Coprocessors - +Hooking into the `RouterService` layer for either [Rhai scripts](https://www.apollographql.com/docs/graphos/routing/customization/rhai) or [Coprocessors](https://www.apollographql.com/docs/graphos/routing/customization/coprocessor) will give you access to the full HTTP request/response before any processing takes place. Here you can add custom logic on what to log and when. ## Debug Router Logs GraphOS Router by default uses the `info` level for its logging. [Enabling other logging levels](https://www.apollographql.com/docs/graphos/reference/router/telemetry/log-exporters/overview) can help debug specific scenarios. It is only reccomended for local or non-production environments. From b09d81159d9e1ca6346d2f1102e5a8a58fab8f35 Mon Sep 17 00:00:00 2001 From: Shane Myrick Date: Thu, 2 Jan 2025 14:20:06 -0800 Subject: [PATCH 7/7] Update debugging-client-requests.mdx --- docs/source/routing/observability/debugging-client-requests.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/routing/observability/debugging-client-requests.mdx b/docs/source/routing/observability/debugging-client-requests.mdx index 115fc83213..51754ffb94 100644 --- a/docs/source/routing/observability/debugging-client-requests.mdx +++ b/docs/source/routing/observability/debugging-client-requests.mdx @@ -37,7 +37,7 @@ Hooking into the `RouterService` layer for either [Rhai scripts](https://www.apo GraphOS Router by default uses the `info` level for its logging. [Enabling other logging levels](https://www.apollographql.com/docs/graphos/reference/router/telemetry/log-exporters/overview) can help debug specific scenarios. It is only reccomended for local or non-production environments. ## Alternative Cloud Services -If you are deploying GraphOS Router to a cloud service, it is likely that you already have access to the raw HTTP logs through other services such as a load balancer. Using the trace id or operation hash, you should be able to find a specific client request to logs for that operation. Check out the docs for popular cloud providers here: +If you are deploying GraphOS Router to a cloud service, it is likely that you already have access to the raw HTTP logs through other services such as a load balancer. Using the trace id or operation hash, you should be able to find a specific client request logs for that operation. Check out the docs for popular cloud providers here: AWS * [AWS CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html)