Skip to content

docs: clarify timeout hierarchy in traffic shaping documentation #8203

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

Open
wants to merge 3 commits into
base: dev
Choose a base branch
from
+22 −0
Open

docs: clarify timeout hierarchy in traffic shaping documentation #8203

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
06db4ad
docs: clarify timeout hierarchy in traffic shaping documentation
abernix Sep 5, 2025
8a872bd
CHANGESET
abernix Sep 5, 2025
aebe839
Apply suggestion from @abernix
abernix Sep 5, 2025
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
5 changes: 5 additions & 0 deletions .changesets/docs_tee_tux_elf_reel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
### Clarify timeout hierarchy for traffic shaping ([PR #8203](https://github.com/apollographql/router/pull/8203))

The documentation reflects more clearly that subgraph timeouts should not be higher than the router timeout or the router timeout will initiate prior to the subgraph.

By [@abernix](https://github.com/abernix) in https://github.com/apollographql/router/pull/8203
17 changes: 17 additions & 0 deletions docs/source/routing/performance/traffic-shaping.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,23 @@
timeout: 50s # If subgraph requests take more than 50 seconds, cancel the request (30 seconds by default)
```

When configuring timeouts, you should set your router timeout to be greater than or equal to your subgraph timeouts. This allows the router to properly handle subgraph timeouts and return appropriate error responses to clients. Ideally, subgraph timeouts should be slightly lower than the router timeout to provide a buffer for the router to process the timeout response.

Check warning on line 83 in docs/source/routing/performance/traffic-shaping.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/routing/performance/traffic-shaping.mdx#L83 

Use the imperative mood for instructions ('set' instead of 'you should set') and favor the present tense for descriptions ('are' instead of 'should be').

```suggestion
When configuring timeouts, set your router timeout to be greater than or equal to your subgraph timeouts. This allows the router to properly handle subgraph timeouts and return appropriate error responses to clients. Ideally, subgraph timeouts are slightly lower than the router timeout to provide a buffer for the router to process the timeout response.
```

For example, a well-configured timeout hierarchy might look like:

```yaml title="router.yaml"
traffic_shaping:
router:
timeout: 60s # Router: 60 seconds
all:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we say "Default for all subgraphs except the ones below" in the comment? The field name "all" is the one that confused me in the first place.

timeout: 30s # Default subgraph: 30 seconds (lower than router)
subgraphs:
products:
timeout: 45s # Products subgraph: 45 seconds (still lower than router)
inventory:
timeout: 20s # Inventory subgraph: 20 seconds
```

<Note>

Since [deferred](/router/executing-operations/defer-support/#what-is-defer) fragments are separate requests, each fragment's request is individually subject to timeouts.
Expand Down