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 and configuration snippets for OTLP/Prometheus
  • Added a Security navigation entry linking to the new cost-control page

[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.

[coderabbitai]

♻️ Duplicate comments (1)

docs/router/security/cost-control.mdx (1)

160-166: ⚠️ Potential issue | 🟡 Minor

Fix query example to match the list return type.

products is declared as [Product], but the query uses edges/node (connection-style). This can confuse readers following the example.

💡 Suggested fix

 query {
   products(first: 20) {   # Multiplier is 20
-    edges { node { name } }
+    name
   }
 }

🤖 Prompt for AI Agents

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

In `@docs/router/security/cost-control.mdx` around lines 160 - 166, The example
query uses connection-style fields (edges/node) but the schema declares products
as a plain list [Product]; update the example in
docs/router/security/cost-control.mdx to select Product fields directly (e.g.,
replace the block using edges { node { name } } with a direct selection like
products(first: 20) { name }) and keep the inline comment about the multiplier;
reference the products field and Product type and remove edges/node usage to
avoid confusion.

🤖 Prompt for all review comments with AI agents

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

Duplicate comments:
In `@docs/router/security/cost-control.mdx`:
- Around line 160-166: The example query uses connection-style fields
(edges/node) but the schema declares products as a plain list [Product]; update
the example in docs/router/security/cost-control.mdx to select Product fields
directly (e.g., replace the block using edges { node { name } } with a direct
selection like products(first: 20) { name }) and keep the inline comment about
the multiplier; reference the products field and Product type and remove
edges/node usage to avoid confusion.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 39da947 and b2a4905.

📒 Files selected for processing (2)

• docs/router/metrics-and-monitoring.mdx
• docs/router/security/cost-control.mdx

[StarpTech]

What dimensions / attributes are tracked?

[ysmolski]

Those metrics use the exact same attribute set as other router request-level metrics (like router.http.requests, router.http.request.duration_milliseconds). Should I mention that?

[StarpTech]

Yes, but we should be repetitive with the overview page. Maybe you can link it.

[ysmolski]

Removed redundancy