docs: update observability/telemetry overview pages (#6563)

Co-authored-by: Edward Huang <edward.huang@apollographql.com> Co-authored-by: Shane Myrick <mail@shanemyrick.com>
apollographql · Feb 7, 2025 · e5359ca · e5359ca
1 parent 9613528
commit e5359ca
Show file tree

Hide file tree

Showing 27 changed files with 433 additions and 117 deletions.
diff --git a/docs/source/reference/router/telemetry/instrumentation/conditions.mdx b/docs/source/reference/router/telemetry/instrumentation/conditions.mdx
@@ -2,6 +2,8 @@
 title: Conditions
 subtitle: Set conditions for when events or instruments are triggered
 description: Set conditions for when events or instruments are triggered in the Apollo GraphOS Router.
+context:
+  - telemetry
 ---
 
 You can set conditions for when an [instrument](/router/configuration/telemetry/instrumentation/instruments) should be mutated or an [event](/router/configuration/telemetry/instrumentation/events) should be triggered.

diff --git a/docs/source/reference/router/telemetry/instrumentation/events.mdx b/docs/source/reference/router/telemetry/instrumentation/events.mdx
@@ -2,6 +2,8 @@
 title: Events
 subtitle: Capture events from the router's request lifecycle
 description: Capture standard and custom events from the Apollo GraphOS Router's request lifecycle services.
+context:
+  - telemetry
 ---
 
 import RouterServices from '../../../../../shared/router-lifecycle-services.mdx';

diff --git a/docs/source/reference/router/telemetry/instrumentation/instruments.mdx b/docs/source/reference/router/telemetry/instrumentation/instruments.mdx
@@ -2,6 +2,8 @@
 title: Instruments
 subtitle: Collect measurements with standard and custom instruments
 description: Create and customize instruments to collect data and report measurements from the Apollo GraphOS Router's request lifecycle services.
+context:
+  - telemetry
 ---
 
 import RouterServices from '../../../../../shared/router-lifecycle-services.mdx';

diff --git a/docs/source/reference/router/telemetry/instrumentation/selectors.mdx b/docs/source/reference/router/telemetry/instrumentation/selectors.mdx
@@ -2,6 +2,8 @@
 title: Selectors
 subtitle: Select data from the router pipeline to extract
 description: Extract and select data from the Apollo GraphOS Router's pipeline services to attach to telemetry.
+context:
+  - telemetry
 ---
 import RouterServices from '../../../../../shared/router-lifecycle-services.mdx';
 

diff --git a/docs/source/reference/router/telemetry/instrumentation/spans.mdx b/docs/source/reference/router/telemetry/instrumentation/spans.mdx
@@ -2,6 +2,8 @@
 title: Spans
 subtitle: Add router lifecycle context to traces
 description: Use spans to add contextual information from the Apollo GraphOS Router or Apollo Router Core to traces displayed by your application performance monitors (APM).
+context:
+  - telemetry
 ---
 
 import RouterServices from '../../../../../shared/router-lifecycle-services.mdx';

diff --git a/docs/source/reference/router/telemetry/instrumentation/standard-attributes.mdx b/docs/source/reference/router/telemetry/instrumentation/standard-attributes.mdx
@@ -2,6 +2,8 @@
 title: OpenTelemetry standard attributes
 subtitle: Attach standard attributes to router telemetry
 description: Attach OpenTelemetry (OTel) standard attributes to Apollo GraphOS Router or Apollo Router Core telemetry.
+context:
+  - telemetry
 ---
 
 import RouterServices from '../../../../../shared/router-lifecycle-services.mdx';

diff --git a/docs/source/reference/router/telemetry/instrumentation/standard-instruments.mdx b/docs/source/reference/router/telemetry/instrumentation/standard-instruments.mdx
@@ -2,6 +2,8 @@
 title: Router Instruments
 subtitle: Standard metric instruments for the router's request lifecycle
 description: Reference of standard metric instruments for the request lifecycle of GraphOS Router and Apollo Router Core. Consumable via the router's metrics exporters.
+context:
+  - telemetry
 ---
 
 ## Standard metric instruments

diff --git a/docs/source/reference/router/telemetry/log-exporters/overview.mdx b/docs/source/reference/router/telemetry/log-exporters/overview.mdx
@@ -2,6 +2,8 @@
 title: Router Logging
 subtitle: Configure logging in the router
 description: Configure logging in the Apollo GraphOS Router or Apollo Router Core. Set the log level and output format.
+context:
+  - telemetry
 ---
 
 GraphOS Router and Apollo Router Core provide built-in logging to capture records about their activity.

diff --git a/docs/source/reference/router/telemetry/log-exporters/stdout.mdx b/docs/source/reference/router/telemetry/log-exporters/stdout.mdx
@@ -2,6 +2,8 @@
 title: Router Logging to stdout
 subtitle: Configure logging to stdout
 description: Configure logging output to stdout in the Apollo GraphOS Router or Apollo Router Core. Format in human-readable text or machine-readable JSON.
+context:
+  - telemetry
 ---
 
 You can configure GraphOS Router or Apollo Router Core logging to be directed to stdout, and its output format can be set to text or JSON.

diff --git a/docs/source/reference/router/telemetry/metrics-exporters/datadog.mdx b/docs/source/reference/router/telemetry/metrics-exporters/datadog.mdx
@@ -2,6 +2,8 @@
 title: Datadog exporter (via OTLP)
 subtitle: Configure the Datadog exporter for metrics
 description: Configure the Datadog exporter for metrics via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 
 Enable and configure the [OTLP exporter](/router/configuration/telemetry/exporters/metrics/otlp) for metrics in the GraphOS Router or Apollo Router Core for use with [Datadog](https://www.datadoghq.com/).

diff --git a/docs/source/reference/router/telemetry/metrics-exporters/dynatrace.mdx b/docs/source/reference/router/telemetry/metrics-exporters/dynatrace.mdx
@@ -2,6 +2,8 @@
 title: Dynatrace exporter (via OTLP)
 subtitle: Configure the Dynatrace exporter for metrics
 description: Configure the Dynatrace exporter for metrics via OpenTelemetry Protocol (OTLP) in the Apollo Router.
+context:
+  - telemetry
 ---
 
 Enable and configure the [OTLP exporter](/router/configuration/telemetry/exporters/metrics/otlp) for metrics in the Apollo Router for use with [Dynatrace](https://dynatrace.com/).

diff --git a/docs/source/reference/router/telemetry/metrics-exporters/new-relic.mdx b/docs/source/reference/router/telemetry/metrics-exporters/new-relic.mdx
@@ -2,6 +2,8 @@
 title: New Relic exporter (via OTLP)
 subtitle: Configure the New Relic exporter for metrics
 description: Configure the New Relic exporter for metrics via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 
 Enable and configure the [OTLP exporter](/router/configuration/telemetry/exporters/metrics/otlp) for metrics in the GraphOS Router or Apollo Router Core for use with [New Relic](https://newrelic.com/).

diff --git a/docs/source/reference/router/telemetry/metrics-exporters/otlp.mdx b/docs/source/reference/router/telemetry/metrics-exporters/otlp.mdx
@@ -2,6 +2,8 @@
 title: OpenTelemetry Protocol (OTLP) exporter
 subtitle: Configure the OpenTelemetry Protocol (OTLP) exporter for metrics
 description: Configure the OpenTelemetry Protocol (OTLP) exporter for metrics in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx';
 import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx';

diff --git a/docs/source/reference/router/telemetry/metrics-exporters/overview.mdx b/docs/source/reference/router/telemetry/metrics-exporters/overview.mdx
@@ -4,6 +4,8 @@ subtitle: Export router metrics
 description: Collect and export metrics from the Apollo GraphOS Router or Apollo Router Core for Prometheus, OpenTelemetry Protocol (OTLP), Datadog, and New Relic.
 redirectFrom:
   - /technotes/TN0015-router-to-apm-via-opentelemetry/
+context:
+  - telemetry
 ---
 
 The GraphOS Router and Apollo Router Core support collection of metrics with [OpenTelemetry](https://opentelemetry.io/), with exporters for:

diff --git a/docs/source/reference/router/telemetry/metrics-exporters/prometheus.mdx b/docs/source/reference/router/telemetry/metrics-exporters/prometheus.mdx
@@ -2,6 +2,8 @@
 title: Prometheus exporter
 subtitle: Configure the Prometheus metrics exporter
 description: Configure the Prometheus metrics exporter endpoint in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 
 Enable and configure the [Prometheus](https://www.prometheus.io/) exporter for metrics in the GraphOS Router or Apollo Router Core.

diff --git a/docs/source/reference/router/telemetry/trace-exporters/datadog.mdx b/docs/source/reference/router/telemetry/trace-exporters/datadog.mdx
@@ -2,6 +2,8 @@
 title: Datadog exporter (via OTLP)
 subtitle: Configure the Datadog exporter for tracing
 description: Configure the Datadog exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx';
 import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx';

diff --git a/docs/source/reference/router/telemetry/trace-exporters/dynatrace.mdx b/docs/source/reference/router/telemetry/trace-exporters/dynatrace.mdx
@@ -2,6 +2,8 @@
 title: Dynatrace exporter (via OTLP)
 subtitle: Configure the Dynatrace exporter for tracing
 description: Configure the Dynatrace exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo Router.
+context:
+  - telemetry
 ---
 
 Enable and configure the [OTLP exporter](/router/configuration/telemetry/exporters/tracing/otlp) for tracing in the Apollo Router for use with [Dynatrace](https://dynatrace.com/).

diff --git a/docs/source/reference/router/telemetry/trace-exporters/jaeger.mdx b/docs/source/reference/router/telemetry/trace-exporters/jaeger.mdx
@@ -2,6 +2,8 @@
 title: Jaeger exporter (via OTLP)
 subtitle: Configure the Jaeger exporter for tracing
 description: Configure the Jaeger exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 
 import BatchProcessorPreamble from "../../../../../shared/batch-processor-preamble.mdx";

diff --git a/docs/source/reference/router/telemetry/trace-exporters/new-relic.mdx b/docs/source/reference/router/telemetry/trace-exporters/new-relic.mdx
@@ -2,6 +2,8 @@
 title: New Relic exporter (via OTLP)
 subtitle: Configure the New Relic exporter for tracing
 description: Configure the New Relic exporter for tracing via OpenTelemetry Protocol (OTLP) in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 
 Enable and configure the [OTLP exporter](/router/configuration/telemetry/exporters/tracing/otlp) for tracing in the GraphOS Router or Apollo Router Core for use with [New Relic](https://newrelic.com/).

diff --git a/docs/source/reference/router/telemetry/trace-exporters/otlp.mdx b/docs/source/reference/router/telemetry/trace-exporters/otlp.mdx
@@ -2,6 +2,8 @@
 title: OpenTelemetry Protocol (OTLP) exporter
 subtitle: Configure the OpenTelemetry Protocol exporter for tracing
 description: Configure the OpenTelemetry Protocol (OTLP) exporter for tracing in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx';
 import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx';

diff --git a/docs/source/reference/router/telemetry/trace-exporters/overview.mdx b/docs/source/reference/router/telemetry/trace-exporters/overview.mdx
@@ -2,6 +2,8 @@
 title: Router Tracing
 subtitle: Collect tracing information from the router
 description: Collect and export tracing information from the Apollo GraphOS Router or Apollo Router Core. Supports OpenTelemetry Protocol (OTLP), Datadog, New Relic, Jaeger, Zipkin.
+context:
+  - telemetry
 ---
 
 The GraphOS Router and Apollo Router Core support collection of traces with [OpenTelemetry](https://opentelemetry.io/), with exporters for:

diff --git a/docs/source/reference/router/telemetry/trace-exporters/zipkin.mdx b/docs/source/reference/router/telemetry/trace-exporters/zipkin.mdx
@@ -2,6 +2,8 @@
 title: Zipkin exporter
 subtitle: Configure the Zipkin exporter for tracing
 description: Enable and configure the Zipkin exporter for tracing in the Apollo GraphOS Router or Apollo Router Core.
+context:
+  - telemetry
 ---
 import BatchProcessorPreamble from '../../../../../shared/batch-processor-preamble.mdx';
 import BatchProcessorRef from '../../../../../shared/batch-processor-ref.mdx';

diff --git a/docs/source/routing/observability/debugging-client-requests.mdx b/docs/source/routing/observability/debugging-client-requests.mdx
@@ -0,0 +1,79 @@
+---
+title: Debugging Client Requests to GraphOS Router
+subtitle: Options for analyzing and debugging incoming requests
+description: Learn how to use GraphOS router telemetry and GraphOS Insights to inspect and debug incoming HTTP client requests.
+context:
+  - telemetry
+---
+
+By default, the GraphOS Router operates [without generating HTTP request logs or exporting telemetry metrics beyond what it sends to GraphOS](/graphos/routing/observability).
+This default minimizes potentially high observability costs that can result from high request volumes.
+If you need more data than the default [GraphOS Insights](/graphos/platform/insights), you can configure your router to collect and export additional telemetry.
+
+## Using GraphOS Insights
+
+GraphOS Studio lets you analyze data from failed requests, such as GraphQL error messages ([if enabled](/graphos/routing/graphos-reporting#errors)) and the ID of the client making the request. You can also [segment your insights data](/graphos/platform/insights/client-segmentation) based on the client ID.
+
+<Tip>
+
+[Learn how to ensure client IDs are included in all requests.](/graphos/routing/observability/client-id-enforcement)
+
+</Tip>
+
+## Enabling additional telemetry
+
+You can instrument [router telemetry](/graphos/routing/observability/telemetry) if you need information outside of what's presented in GraphOS Studio to debug client requests.
+
+<Note>
+
+If you want to debug client requests in your own environment, Apollo recommends first doing so in a non-production environment or using logic to debug on a per-request basis.
+
+</Note>
+
+### Logging requests
+
+You can conditionally include request bodies, including GraphQL operations, in your telemetry based on specific [conditions](/graphos/reference/router/telemetry/instrumentation/conditions). Apply these conditions on a router request [event](/graphos/reference/router/telemetry/instrumentation/events) like so:
+
+```yaml title="router.yaml"
+telemetry:
+  instrumentation:
+    events:
+      router:
+        request:
+          level: info
+          condition: # Only log the router request if you sent `x-log-request` with the value `enabled`
+            eq:
+            - request_header: x-log-request
+            - "enabled"
+```
+
+### Debugging router logs
+
+By default, the router uses the `info` level for its logging. [Enabling other logging levels](/graphos/reference/router/telemetry/log-exporters/overview) can help debug specific scenarios. Using non-`info` level configurations is only recommended for local or non-production environments.
+
+## Rhai scripts and coprocessors
+
+Hooking into the router service layer with either [Rhai scripts](/graphos/routing/customization/rhai) or [coprocessors](/graphos/routing/customization/coprocessor) gives you access to the full HTTP request before processing occurs. You can use either Rhai scripts or coprocessors to add custom logic for what to log and when.
+
+See the Apollo Solutions ["Hello World" coprocessor](https://github.com/apollosolutions/example-coprocessor-helloworld) for an example of a coprocessor that simply logs the router's payload.
+
+<SolutionsNote />
+
+## Alternative cloud services
+
+If you are deploying the router to a cloud service, you likely already have access to the raw HTTP logs through other services like load balancers. You should be able to find specific client request logs for a particular operation using the operation hash or trace ID. Refer to the docs for your cloud providers for more information. Popular cloud provider links are provided below.
+
+### Amazon Web Services
+
+- [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)
+
+### Google Cloud Platform
+
+- [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)
+
+### Microsoft 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)