feat: add ability to log operation complexity

[alepane21]

This PR allows complexity metrics to be logged in the access logs. It also add a missing wait on the complexity calculation cache.

Summary by CodeRabbit

• New Features

  • Added query complexity metrics to request expressions, access logs, and dynamic tracing attributes, including depth, field counts, root-field aliases, and cache status.
  • Added Redis connection documentation covering URL configuration, clustering, TLS, pooling, and validation behavior.

• Documentation

  • Expanded guidance and examples for complexity reporting, enforcement, and observability.
  • Added Redis configuration references for event providers, rate limits, and storage.

• Tests

  • Added coverage for successful, cached, and rejected operations, including structured logging and tracing scenarios.

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• If applicable, I have provided instructions for reviewers for manually validating my changes.
• Documentation has been updated on https://github.com/wundergraph/docs-website.
• I have read the Contributors Guide.

Open Source AI Manifesto

This project follows the principles of the Open Source AI Manifesto. Please ensure your contribution aligns with its principles.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wundergraphinc	🟢 Ready	View Preview	Aug 20, 2026, 4:18 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1e1dcd69-fbe8-493f-a5e8-cb61af6efe5f

📥 Commits

Reviewing files that changed from the base of the PR and between e872ea1 and 77c6a7f.

📒 Files selected for processing (1)

• router/core/graphql_prehandler.go

Included review availability: 4 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

Walkthrough

The router exposes query complexity metrics through operation expressions, access logs, and tracing. It adds bucket classification, cache synchronization, response-cache handler wiring, integration tests, and documentation for complexity and Redis configuration.

Changes

Query Complexity Observability

Layer / File(s)	Summary
Expression fields and bucket classification router/internal/expr/expr.go, router/internal/expr/request_operation_bucket_visitor.go, router/internal/expr/request_operation_bucket_visitor_test.go	Adds five query complexity fields to Operation. Classifies them under BucketQueryComplexity and verifies bucket precedence.
Runtime context and observability integration router/core/graphql_prehandler.go, router-tests/observability/structured_logging_test.go, router-tests/telemetry/telemetry_test.go	Populates complexity values during validation and tests access-log and tracing output.
Configuration and expression documentation docs-website/router/access-logs.mdx, docs-website/router/configuration.mdx, docs-website/router/configuration/template-expressions.mdx	Documents complexity modes, logging fields, expression fields, calculation conditions, and example expressions.

Redis Configuration Documentation

Layer / File(s)	Summary
Redis connection and provider settings docs-website/router/configuration.mdx	Documents Redis URL parameters, TLS, validation failures, pool behavior, cluster settings, and shared settings links for Redis-backed providers.

Cache Wiring

Layer / File(s)	Summary
Cache synchronization and handler options router/core/graph_server.go	Waits for pending complexity-cache writes and passes the configured response cache and fallback TTL to GraphQL handler options.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 77c6a

No actionable merge-blocking risk remains based on the supplied evidence; the PR is merge-ready after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 5 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding support for logging operation complexity.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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

[github-actions]

Router-nonroot image scan passed

✅ No security vulnerabilities found in image:

ghcr.io/wundergraph/cosmo/router:sha-9fdd7a313f21539a2966abccb93cc2b36caa5b93-nonroot

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.86%. Comparing base (7530061) to head (77c6a7f).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3176      +/-   ##
==========================================
- Coverage   71.35%   62.86%   -8.49%     
==========================================
  Files         336      265      -71     
  Lines       49535    31493   -18042     
  Branches     6116        0    -6116     
==========================================
- Hits        35345    19798   -15547     
+ Misses      14164    10160    -4004     
- Partials       26     1535    +1509     

Files with missing lines	Coverage Δ
router/core/graph_server.go	85.81% <100.00%> (ø)
router/core/graphql_prehandler.go	88.46% <100.00%> (ø)
router/internal/expr/expr.go	95.74% <ø> (ø)
.../internal/expr/request_operation_bucket_visitor.go	84.21% <100.00%> (ø)

... and 597 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}