feat(federation): add env var for MAX_NON_LOCAL_SELECTIONS

[lrlna]

---

Adds a environment variable for MAX_NON_LOCAL_SELECTIONS const used in query planning traversal. This is an undocumented env var, as it's intended for internal use.

It is read during query planning config initialisation to make sure that the cache is refreshed when the env var changes. To make that happen, QueryPlannerConfig now has max_non_local_selection as an additional field.

This additionally adds a metric for tracking current number of non-local selections, which is a histogram available under apollo.router.query_planning.plan.non_local_selections. Given that it is such an internal query planning detail, I can be persuaded to not add this metric also, so let me know what you think!

I also considered adding a counter metric for when the limit is exceeded. The issue is that that error (QueryPlanComplexityExceeded) fires for a bunch of other very internal to query planning limits, so that felt like out of scope for this work.

This is still kept as 500 when surfaced to the end user, again due to the internal nature of this functionality.

Checklist

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

• PR description explains the motivation for the change and relevant context for reviewing
• PR description links appropriate GitHub/Jira tickets (creating when necessary)
• Changeset is included for user-facing changes
• Changes are compatible¹
• Documentation² completed
• Performance impact assessed and acceptable
• Metrics and logs are added³ and documented
• Tests added and passing⁴
  • Unit tests
  • Integration tests
  • Manual tests, as necessary

Exceptions

Note any exceptions here

Notes

Footnotes

1. It may be appropriate to bring upcoming changes to the attention of other (impacted) groups. Please endeavour to do this before seeking PR approval. The mechanism for doing this will vary considerably, so use your judgement as to how and when to do this. ↩

2. Configuration is an important part of many changes. Where applicable please try to document configuration examples. ↩

3. A lot of (if not most) features benefit from built-in observability and debug-level logs. Please read this guidance on metrics best-practices. ↩

4. Tick whichever testing boxes are applicable. If you are adding Manual Tests, please document the manual testing (extensively) in the Exceptions. ↩

[apollo-librarian]

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 2 changed, 0 removed

* graphos/routing/(latest)/observability/router-telemetry-otel/enabling-telemetry/standard-instruments.mdx
* graphos/routing/(latest)/performance/traffic-shaping.mdx

Build ID: 4f260efb2223832b6935873a
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/4f260efb2223832b6935873a

---

⚠️ AI Style Review — 1 Issue Found

Summary

The documentation has been updated to align with several style guide standards. Key changes include: Framing & Voice: Adopted authoritative, imperative language using 'you/your' instead of passive phrasing, and replaced 'utilized' with 'use'. Language & Tense: Shifted to present tense, clarified idiomatic phrases with proper articles, and replaced 'may' with 'might' for potential occurrences. Formatting & Structure: Applied code font for technical numeric values, removed articles before standalone feature names, and converted list items into short, unpunctuated fragments while moving context to surrounding text.

Duration: 3382ms
Review Log: View detailed log

This review is AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

[BrynCooke]

Mostly it's the redis key thing that needs fixing.

[BrynCooke]

This histogram inherits the default bucket boundaries, which stop at 10, so estimates near the 100,000 limit all fall into the +Inf bucket. Provide count-appropriate boundaries (including the region around the limit) and test bucket placement; otherwise drop it from this change.

[BrynCooke]

“Non-local selections” and “option exploration” don't tell an operator what this metric is useful for. Explain its relationship to the planning safety limit instead:

Shows how close successfully planned queries come to a query-planning safety limit. The router estimates the work needed to plan each query and rejects queries whose estimate exceeds the limit (100,000 by default).

Update the instrument description to match. This also makes the limitation clear: the histogram cannot show how far a rejected query exceeded the limit.

[lrlna]

Your suggestion makes it less clear what this metric does. But let me see if I can word what I already have slightly better.

[BrynCooke]

This release note exposes an internal constant and advertises an “undocumented” setting without explaining the user benefit. Replace the heading and first paragraph with “Allow support-guided adjustment of query-planning protection” and “Support can adjust a query-planning safety limit for legitimate operations that exceed the default.” If the histogram remains, replace the second paragraph with “Adds apollo.router.query_planning.plan.non_local_selections, a histogram of estimated selections requiring query-planning exploration for successful, newly generated plans.”

[lrlna]

Hmmmm I don't know about your wording 😅 . I feel that mine is clearer.

[lrlna]

I've removed the mention of the env var and just kept the changelog around the metric.