docs: add extended reference reporting (#5558)

docs/source/configuration/overview.mdx

@@ -578,7 +578,6 @@ The default value of `experimental_parallelism` is `1`.
 
 In practice, you should tune `experimental_parallelism` based on metrics and benchmarks gathered from your router.
 
-
 <MinVersion version="1.49.0">
 
 ### Enhanced operation signature normalization
@@ -587,10 +586,10 @@ In practice, you should tune `experimental_parallelism` based on metrics and ben
 
 <ExperimentalFeature />
 
+Beginning in v1.49.0, the router supports enhanced operation signature normalization.
 Apollo's legacy operation signature algorithm removes information about certain fields, such as input objects and aliases.
 This removal means some operations may have the same normalized signature though they are distinct operations.
 
-Beginning in v1.49.0, the router supports enhanced operation signature normalization.
 Enhanced normalization incorporates [input types](#input-types) and [aliases](#aliases) in signature generation.
 It also includes other improvements that make it more likely that two operations that only vary slightly have the same signature.
 
@@ -742,6 +741,101 @@ query AliasedQuery {
 }
 ```
 
+<MinVersion version="1.50.0">
+
+### Extended reference reporting
+
+</MinVersion>
+
+<ExperimentalFeature />
+
+<EnterpriseFeature linkWithAnchor="https://www.apollographql.com/pricing#graphos-router" />
+
+Beginning in v1.50.0, you can configure the router to report enum and input object references for enhanced insights and operation checks.
+Apollo's legacy reference reporting doesn't include data about enum values and input object fields, meaning you can't view enum and input object field usage in GraphOS Studio.
+Legacy reporting can also cause [inaccurate operation checks](#enhanced-operation-checks).
+
+Configure extended reference reporting in `router.yaml` with the `telemetry.apollo.experimental_apollo_metrics_reference_mode` option like so:
+
+```yaml title="router.yaml"
+telemetry: 
+  apollo:
+    experimental_apollo_metrics_reference_mode: extended # Default is legacy
+```
+#### Configuration effect timing
+
+Once you configure extended reference reporting, you can view enum value and input field usage alongside object [field usage in GraphOS Studio](/graphos/metrics/field-usage) for all subsequent operations.
+
+Configuring extended reference reporting automatically turns on [enhanced operation checks](#enhanced-operation-checks), though you won't see an immediate change in your operations check behavior.
+
+This delay is because operation checks rely on historical operation data.
+To ensure sufficient data to distinguish between genuinely unused values and those simply not reported in legacy data, enhanced checks require some operations with extended reference reporting turned on.
+
+#### Enhanced operation checks
+
+Thanks to extended reference reporting, operation checks can more accurately flag issues for changes to enum values and input object fields. See the comparison table below for differences between standard operation checks based on legacy reference reporting and enhanced checks based on extended reference reporting.
+
+<table class="field-table api-ref">
+<tr>
+<th style="min-width: 100px;"></th>
+<th style="min-width: 200px;">
+Standard Check Behavior<br/>
+(Legacy reference reporting)
+</th>
+<th>
+Enhanced Check Behavior<br/>
+(Extended reference reporting)
+</th>
+</tr>
+<tr>
+<td>
+
+##### Enum value removal
+
+</td>
+<td>Removing any enum values is considered a breaking change if any operations use the enum.</td>
+<td>Removing enum values is only a breaking change if historical operations use the specific enum value(s) that were removed.</td>
+</tr>
+<tr>
+<td>
+
+##### Default argument changes for input object fields
+
+</td>
+
+<td>Changing or removing a default argument is generally considered a breaking change, but changing or removing default values for input object fields isn't.</td>
+<td>
+
+Changing or removing default values for input object fields is considered a breaking change.
+You can [configure checks to ignore default values changes](/graphos/delivery/schema-checks/#ignored-conditions-settings).
+
+</td>
+</tr>
+<tr>
+<td>
+
+##### Nullable input object field removal
+</td>
+<td>Removing a nullable input object field is always considered a breaking change.</td>
+<td>Removing a nullable input object field is only considered a breaking change if the nullable field is present in historical operations. If the nullable field is always omitted in historical operations, its removal isn't considered a breaking change.</td>
+</tr>
+<tr>
+<td>
+
+##### Changing nullable input object fields to non-nullable
+
+</td>
+<td>Changing a nullable input object field to non-nullable is considered a breaking change.</td>
+<td>Changing a nullable input object field to non-nullable is only considered a breaking change if the field had a <code>null</code> value in historical operations. If the field was always a non-null value in historical operations, changing it to non-nullable isn't considered a breaking change.</td>
+</tr>
+</table>
+
+<Note>
+
+You won't see an immediate change in checks behavior when you first turn on extended reference reporting.
+[Learn more.](#configuration-effect-timing)
+
+</Note>
 
 ### Safelisting with persisted queries