Re-org-router-observability by robert113289 · Pull Request #8183 · apollographql/router

robert113289 · 2025-09-02T17:57:03Z

Summary

This Pull Request re-organizes and enhances the documentation structure for observability, telemetry, and performance monitoring in the Apollo GraphOS Router. It primarily focuses on restructuring content, modifying links, integrating redirects for legacy paths, and ensuring consistency across documentation. JIra RR-305

This branch has a sister branch in docs-rewrite. In order to preview the PR you will need to pull both branches down and run locally. The librarian preview in the comments below does not work because there are related changes in the https://github.com/apollographql/docs-rewrite/pull/758 PR that needs to be merged at the same time as this PR.

Main Changes:

Sidebar Updates: Significant restructuring of the navigation hierarchy to improve content discoverability in the observability and telemetry sections.
Documentation Relocation: Files related to telemetry, metrics, and tracing exporters have been moved to new directories or renamed for better organization (e.g., OpenTelemetry, Datadog, Dynatrace, Jaeger, Prometheus, and more).
Redirect Integrations: Incorporates extensive redirectFrom entries to handle existing links to legacy documentation paths and prevent dead links.
Content Enhancements: Very minor updates to file descriptions, paths, and key references in the documentation to ensure better clarity and relevance.
Media Source Updates: Adjusts image paths in specific MDX files for alignment with the new directory structure.

Outcome

These changes focus on improving user experience and ensuring that observability-related documentation is easier to navigate and utilize. GraphOs insights documentation and router otel telemetry documentation are now in separate sections. Users will be able to find all of the apm specific documentation in a dedicated folder for their apm of choice. This allows room for future PRs that will add documentation for apm specific dashboards and monitoring recommendations.

The Plan

Excalidraw

Checklist

Complete the checklist (and note appropriate exceptions) before the PR is marked ready-for-review.

Exceptions
This is a docs only PR. Checklist items around Unit testing and router compatibility need not appy.

apollo-librarian · 2025-09-02T17:57:12Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 1 changed, 32 removed

* graphos/routing/(latest)/_sidebar.yaml
- graphos/routing/(latest)/observability/telemetry/instrumentation/instruments.mdx
- graphos/routing/(latest)/observability/telemetry/instrumentation/events.mdx
- graphos/routing/(latest)/observability/telemetry/instrumentation/conditions.mdx
- graphos/routing/(latest)/observability/telemetry/instrumentation/spans.mdx
- graphos/routing/(latest)/observability/telemetry/instrumentation/standard-attributes.mdx
- graphos/routing/(latest)/observability/telemetry/instrumentation/standard-instruments.mdx
- graphos/routing/(latest)/observability/telemetry/instrumentation/selectors.mdx
- graphos/routing/(latest)/observability/telemetry/log-exporters/overview.mdx
- graphos/routing/(latest)/observability/telemetry/log-exporters/stdout.mdx
- graphos/routing/(latest)/observability/telemetry/metrics-exporters/overview.mdx
- graphos/routing/(latest)/observability/telemetry/metrics-exporters/datadog.mdx
- graphos/routing/(latest)/observability/telemetry/metrics-exporters/dynatrace.mdx
- graphos/routing/(latest)/observability/telemetry/metrics-exporters/new-relic.mdx
- graphos/routing/(latest)/observability/telemetry/metrics-exporters/otlp.mdx
- graphos/routing/(latest)/observability/telemetry/metrics-exporters/prometheus.mdx
- graphos/routing/(latest)/observability/telemetry/trace-exporters/overview.mdx
- graphos/routing/(latest)/observability/telemetry/trace-exporters/datadog.mdx
- graphos/routing/(latest)/observability/telemetry/trace-exporters/dynatrace.mdx
- graphos/routing/(latest)/observability/telemetry/trace-exporters/new-relic.mdx
- graphos/routing/(latest)/observability/telemetry/trace-exporters/otlp.mdx
- graphos/routing/(latest)/observability/telemetry/trace-exporters/zipkin.mdx
- graphos/routing/(latest)/observability/telemetry/trace-exporters/jaeger.mdx
- graphos/routing/(latest)/observability/telemetry/index.mdx
- graphos/routing/(latest)/observability/subgraph-error-inclusion.mdx
- graphos/routing/(latest)/observability/debugging-client-requests.mdx
- graphos/routing/(latest)/observability/client-id-enforcement.mdx
- graphos/routing/(latest)/observability/debugging-subgraph-requests.mdx
- graphos/routing/(latest)/observability/index.mdx
- graphos/routing/(latest)/observability/otel-traces-to-prometheus.mdx
- graphos/routing/(latest)/observability/federated-trace-data.mdx
- graphos/routing/(latest)/observability/otel.mdx
- graphos/routing/(latest)/graphos-reporting.mdx

Build ID: 7fcb4694f68e273df1551517
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/7fcb4694f68e273df1551517

DMallare · 2025-09-09T16:20:27Z

Question: Since we are reorganizing a lot of information do we need to worry about customers who have any current pages bookmarked in this section and would now experience 404s. Have we considered adding redirects?

robert113289 · 2025-09-09T17:31:49Z

Question: Since we are reorganizing a lot of information do we need to worry about customers who have any current pages bookmarked in this section and would now experience 404s. Have we considered adding redirects?

@DMallare, great question! everything has redirects from their old url. no bookmarks will be broken. check out the top of the *.mdx files for a section like the one below to see how I've configured the redirects.

redirectFrom:
    - /graphos/routing/old/url/path/

tninesling

Love the idea to improve the organization here! Left a few suggestions to think about

tninesling · 2025-09-09T18:58:22Z

docs/source/_sidebar.yaml

I think Instruments, Events, Spans, Attributes, Conditions, and Selectors should stay as peers in this structure. Selectors are used with Attributes, Conditions, Spans, Events, and Instruments. Conditions can be applied to the first three. Since these are somewhat intertwined, I think the previous structure made more sense.

I agree that folks probably want to know the standard instruments first to get started up, so we can keep Instruments as the first page. Maybe it's worth merging Instruments with Standard Instruments?

i removed the MELT folder from the tree so that Metrics, Events, Traces, Selectors, and Conditions are on the same Level

Maybe it's worth merging Instruments with Standard Instruments?

I looked into this and it would result in a very long page unfortunately.

tninesling · 2025-09-09T19:00:06Z

docs/source/_sidebar.yaml

I like this change to group the different APM docs together! Some of these pages seem fairly short, so it might make things easier for everyone if we just merge the sub-pages together (ie. have a single page for each APM that covers metrics, traces, etc).

i agree, but I won't be able to get the old bookmarks to navigate to the correct subsection.

Redirect limitations
Redirects don't currently support redirecting to or from anchors.

I could combine New Relic and Dynatrace but that's about it.

Datadog would be too long. I could do it by splitting off the old Datadog native configuration into its own page, but that would break old links to it.

Prometheus isn’t all that long, but I believe its two pages, metrics and trace metrics, are better off being separate since they don’t have the same concept of using the same exporter like the others do where you use the otlp exporter for both metrics and traces.

Zipkin and Jaeger only have one page already.

docs/source/_sidebar.yaml

alyssahursh

This looks great, Robert! Thanks for putting so much thought and care into this, and for organizing the work so clearly that it's easy to review.

mabuyo

++ to Alyssa's comment! I really appreciate the cleanliness of organizing this work. Besides the minor comment, two things:

cc @BlenderDude's, I see redirectFroms set up which is great, is there anything else we can do or have done in the past to catch any broken links with a restructure like this?
This is a part of the docs I don't visit very often and a topic I don't know much about. I see some teammates already gave their reviews, which is great. I would recommend also pulling in other folks who use this part of the docs more (maybe someone from Solutions?).

Giving my approval because these are non-blocking comments!

docs/source/_sidebar.yaml

mabuyo · 2025-09-19T16:54:05Z

Looks like some file conflicts popped up! After fixing those, LGTM to hit merge (tho my previous PR review comment still applies!).

… in side-bar

devfreddy-apollo

I love it. Very logical split between GraphOS data and Router Telemetry. There's a place for guides / longer form content now. Really liking the more natural fit of Instruments/standard instruments under a Metrics section.

pokeefe-apollo · 2025-10-03T01:11:55Z

LGTM

This comment has been minimized.

Sign in to view

robert113289 force-pushed the kirkum/RR-305-re-org-router-observability branch 4 times, most recently from b92962e to 8ca54ac Compare September 5, 2025 18:10

tninesling reviewed Sep 9, 2025

View reviewed changes

robert113289 force-pushed the kirkum/RR-305-re-org-router-observability branch 3 times, most recently from 23a6e41 to 6410784 Compare September 12, 2025 17:04

alyssahursh approved these changes Sep 12, 2025

View reviewed changes

robert113289 marked this pull request as ready for review September 12, 2025 18:39

robert113289 requested a review from a team as a code owner September 12, 2025 18:39

mabuyo approved these changes Sep 18, 2025

View reviewed changes

docs/source/_sidebar.yaml Outdated Show resolved Hide resolved

mabuyo reviewed Sep 19, 2025

View reviewed changes

docs/source/_sidebar.yaml Outdated Show resolved Hide resolved

robert113289 added 12 commits September 19, 2025 09:55

Move events, instruments, and spans to melt

6203842

Move conditions and selectors to enabling-telemetry

2f60faa

Move standard instruments and standard attributes to melt

7b74b86

Move subgraph observability to enabling-telemetry usage guides

fafbf13

Move client observability to enabling-telemetry usage guides

e0e020e

Move Metric Exporters otlp to telemetry-pipelines

3a69628

Move Trace Exporters otlp to telemetry-pipelines

4e0114b

Move Log Exporters stdout to telemetry-pipelines

1c7b6ab

Move datadog files to apm-guides/datadog

4cf8a30

Move new relic files to apm-guides/new-relic

24bfc60

Move prometheus files to apm-guides/prometheus

0e3d9c1

Move zipkin files to apm-guides/zipkin

d09086c

robert113289 added 19 commits September 19, 2025 09:55

Rename Set up Otel to Instrumenting Subgraphs

c0bb9cd

Remove bad link

b88d9a0

Rename router telemetry overview

6ae038a

Move router telemetry overview to /observability

791b888

Create GraphOS and Router(OTEL) subfolder in /observability

91e7822

Move graphos files into observability/graphos

7bc8c61

Move enabling-telemetry folder into observability/router-telemetry-otel

6e333a7

Move telemetry-pipelines folder into observability/router-telemetry-otel

9f09209

Move router-telemetry-overview into observability/router-telemetry-otel

35dd799

Rename router-telemetry-overview to index

d6965fa

Move graphos-reporting to observability/graphos

f9afac3

Move apm-guides to observability/router-telemetry-otel

644cdf5

Rename agent folder to connecting to datadog

777ec75

Fix redirection to router-telemetry-otel

aa997c5

Remove MELT folder from tree

7fc1232

Rename Enabling and Customizing Telemetry Data to just Telemetry Data

7eea088

Move Operation Metrics Reporting above the older Federated Trace Data…

24b3ff5

… in side-bar

Address AI librarian style changes

5870ab6

Move datadog metrics and traces up in sidebar

2ab4574

robert113289 force-pushed the kirkum/RR-305-re-org-router-observability branch from 8f18a06 to 2ab4574 Compare September 19, 2025 16:55

Add changeset entry

62bf342

devfreddy-apollo assigned devfreddy-apollo and unassigned devfreddy-apollo Sep 19, 2025

devfreddy-apollo self-requested a review September 19, 2025 19:25

devfreddy-apollo approved these changes Sep 19, 2025

View reviewed changes

BlenderDude merged commit d5af172 into dev Sep 22, 2025
15 checks passed

BlenderDude deleted the kirkum/RR-305-re-org-router-observability branch September 22, 2025 17:32

abernix mentioned this pull request Oct 27, 2025

prep release: v2.8.0 #8495

Merged

Conversation

robert113289 commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Main Changes:

Outcome

The Plan

Uh oh!

This comment has been minimized.

apollo-librarian bot commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

Uh oh!

DMallare commented Sep 9, 2025

Uh oh!

robert113289 commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tninesling left a comment

Choose a reason for hiding this comment

Uh oh!

tninesling Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

robert113289 Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

robert113289 Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tninesling Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

robert113289 Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

robert113289 Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alyssahursh left a comment

Choose a reason for hiding this comment

Uh oh!

mabuyo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mabuyo commented Sep 19, 2025

Uh oh!

devfreddy-apollo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pokeefe-apollo commented Oct 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

robert113289 commented Sep 2, 2025 •

edited

Loading

apollo-librarian bot commented Sep 2, 2025 •

edited

Loading

robert113289 commented Sep 9, 2025 •

edited

Loading

robert113289 Sep 9, 2025 •

edited

Loading