Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add extended reference reporting #5558

Merged
merged 1 commit into from
Jun 28, 2024
Merged

docs: add extended reference reporting #5558

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 96 additions & 2 deletions docs/source/configuration/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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

Expand Down
Loading