Add documentation describing gitlab:graphql:analyze

doc/development/api_graphql_styleguide.md

@@ -67,6 +67,10 @@ Complexity is explained [on our client-facing API page](../api/graphql/index.md#
 Fields default to adding `1` to a query's complexity score, but developers can
 [specify a custom complexity](#field-complexity) when defining a field.
 
+To estimate the complexity of a query, you can run the
+[`gitlab:graphql:analyze`](rake_tasks.md#analyze-graphql-queries)
+Rake task.
+
 ### Request timeout
 
 Requests time out at 30 seconds.

doc/development/rake_tasks.md

@@ -261,6 +261,48 @@ bundle exec rake db:obsolete_ignored_columns
 
 Feel free to remove their definitions from their `ignored_columns` definitions.
 
+## Validate GraphQL queries
+
+To check the validity of one or more of our front-end GraphQL queries,
+run:
+
+```shell
+# Validate all queries
+bundle exec rake gitlab::graphql:validate
+# Validate one query
+bundle exec rake gitlab::graphql:validate[path/to/query.graphql]
+# Validate a directory
+bundle exec rake gitlab::graphql:validate[path/to/queries]
+```
+
+This prints out a report with an entry for each query, explaining why
+each query is invalid if it fails to pass validation.
+
+We strip out `@client` fields during validation so it is important to mark
+client fields with the `@client` directive to avoid false positives.
+
+## Analyze GraphQL queries
+
+Analogous to `ANALYZE` in SQL, we can run `gitlab:graphql:analyze` to
+estimate the of the cost of running a query.
+
+Usage:
+
+```shell
+# Analyze all queries
+bundle exec rake gitlab::graphql:analyze
+# Analyze one query
+bundle exec rake gitlab::graphql:analyze[path/to/query.graphql]
+# Analyze a directory
+bundle exec rake gitlab::graphql:analyze[path/to/queries]
+```
+
+This prints out a report for each query, including the complexity
+of the query if it is valid.
+
+The complexity depends on the arguments in some cases, so the reported
+complexity is a best-effort assessment of the upper bound.
+
 ## Update GraphQL documentation and schema definitions
 
 To generate GraphQL documentation based on the GitLab schema, run: