document the cost directives

[ysmolski]

It includes what is done, differences with IBM spec, and what is not done yet.

Summary by CodeRabbit

• Documentation
  • Added comprehensive cost-control docs covering goals, measurement modes (measure/enforce), configuration, directive-based customization (@cost, @listsize), examples, best practices, and integration guidance for routing, rate limiting, and billing
  • Introduced cost-analysis metrics (router.graphql.operation.cost.estimated, .actual, .delta) with monitoring guidance
  • Added a Security navigation entry linking to the new cost-control page

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

Walkthrough

Adds a new Router cost-control documentation page and navigation entry, and extends Router metrics docs with a "Cost Analysis metrics" section containing three new cost-related histogram metrics plus a small formatting tweak.

Changes

Cohort / File(s)	Summary
Navigation Configuration docs/docs.json	Added router/security/cost-control to the Security group navigation after router/security/hardening-guide.
Cost-Control Documentation docs/router/security/cost-control.mdx	New MDX doc describing GraphQL Router cost analysis: overview, federation-aware cost accounting, estimated vs actual costs, list multiplication, @cost and @listSize directive usage, config options and env vars (enabled, mode, max_estimated_limit, estimated_list_size), enforcement modes, telemetry/metrics, examples, best practices, access from custom modules, and unimplemented features.
Metrics Documentation docs/router/metrics-and-monitoring.mdx	Added "Cost Analysis metrics" section and three Int64 histogram metrics: router.graphql.operation.cost.estimated, router.graphql.operation.cost.actual, router.graphql.operation.cost.delta; also converted a GraphQL planning time reference into a bullet item.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'document the cost directives' directly aligns with the main objective of the PR, which is to add comprehensive documentation for cost directives, including @cost and @listSize directives with their configuration and usage.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/router/security/cost-control.mdx`:
- Around line 216-223: Add an inline cross-link from the "Telemetry" (and/or
"Metrics" subsection) text to the existing "Metrics & Monitoring" guide so
readers can jump to detailed export/query instructions; update the paragraph
that mentions OTEL/Prometheus and operation-level attributes (look for the
"Telemetry" heading and the "### Metrics" subsection) to append a parenthetical
or sentence like "See Metrics & Monitoring for exporting and querying metrics"
that links to the guide's doc page.
- Around line 255-308: Update the documentation to consistently use the
canonical config key and directive names: replace occurrences of "list_size" and
"@list_size" in the Best Practices text with "estimated_list_size" and
"@listSize" so they match the config table and directive definitions; ensure
examples and explanatory text (e.g., the YAML snippet under "Start with Measure
Mode" and mentions in "Pick Parameters for `@list_size` Carefully" and "Design for
Pagination") use estimated_list_size and `@listSize`, and keep other symbols like
slicingArguments and `@cost` unchanged.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/router/security/cost-control.mdx`:
- Around line 153-169: The example misuses `@listSize` on the products field which
returns a ProductConnection (non-list); either change the products field to
return a list type (e.g., [Product]) so `@listSize` and slicingArguments like
"first" clearly apply, or add an explicit note explaining how to annotate
connection-style fields (ProductConnection) if the router reads connection
arguments (e.g., that `@listSize` should reference the connection's paging
argument like "first" and that connection types are supported/unsupported).
Update the example and/or surrounding text to use the symbols products,
ProductConnection, searchResults, and `@listSize` so readers aren’t misled.
- Around line 14-17: Update the paragraph describing cost analysis to explicitly
state that only "enforce" mode rejects operations exceeding the configured limit
while "measure" mode allows those operations to proceed (but records/alerts the
exceedance); edit the sentence mentioning "Operations exceeding the configured
limit are rejected immediately" to be conditional on the mode (e.g., "In enforce
mode, operations... are rejected immediately; in measure mode they are allowed
but tracked"), and ensure references to "cost analysis", "measure mode" and
"enforce mode" are used so readers can clearly see mode-specific behavior.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/router/security/cost-control.mdx`:
- Around line 247-248: The Prometheus comment is inconsistent with the delta
sign: router_graphql_operation_cost_delta is defined positive when estimated >
actual (cheaper-than-estimated), but the heading says "Operations where actual
cost exceeds the estimate." Update the heading/comment to match the metric
definition or invert the selector; specifically either change the text to
"Operations where actual cost is lower than the estimate
(cheaper-than-estimated)" to match router_graphql_operation_cost_delta > 0, or
change the check to router_graphql_operation_cost_delta < 0 and adjust
surrounding wording to "actual cost exceeds the estimate."

---

Duplicate comments:
In `@docs/router/security/cost-control.mdx`:
- Around line 160-166: The GraphQL example uses the Relay connection shape
(edges { node { name } }) but the products field actually returns a plain list
[Product]; update the example query so it directly selects the Product field(s)
(e.g., products(first: 20) { name }) instead of edges/node, referencing the
products and name fields to match the [Product] return type.