GraphQL Inspector - Audit

Expert knowledge of GraphQL Inspector's audit command for analyzing operation complexity and identifying potential performance issues.

Overview

The audit command analyzes GraphQL operations to provide metrics about query depth, directive count, alias count, and complexity. This helps identify operations that may cause performance issues before they reach production.

Core Commands

Basic Audit

Audit all GraphQL operations

npx @graphql-inspector/cli audit './src/**/*.graphql'

Audit operations from TypeScript files

npx @graphql-inspector/cli audit './src/**/*.tsx'

Audit with multiple patterns

npx @graphql-inspector/cli audit './packages//*.graphql' './apps//*.tsx'

Audit with Schema

Audit against a specific schema

npx @graphql-inspector/cli audit './src/**/*.graphql' --schema './schema.graphql'

Metrics Analyzed

Query Depth

Measures the maximum nesting level of a query:

Depth: 4

query UserPosts { user { # 1 posts { # 2 comments { # 3 author { # 4 name } } } } }

High depth operations can cause:

• Slow database queries (N+1 problems)

• Memory pressure on resolvers

• Long response times

Alias Count

Counts the number of field aliases:

Alias count: 3

query MultipleUsers { admin: user(id: "1") { name } moderator: user(id: "2") { name } member: user(id: "3") { name } }

High alias counts can:

• Multiply database queries

• Increase payload size

• Indicate query batching abuse

Directive Count

Counts directives used in the operation:

Directive count: 4

query ConditionalData($includeEmail: Boolean!, $skipPhone: Boolean!) { user { name email @include(if: $includeEmail) phone @skip(if: $skipPhone) avatar @cacheControl(maxAge: 3600) bio @deprecated } }

Token Count

Counts the total tokens in the operation:

Higher token count = more complex query

query ComplexQuery { users( filter: { status: ACTIVE, role: ADMIN } orderBy: { field: NAME, direction: ASC } pagination: { limit: 10, offset: 0 } ) { id name email role createdAt updatedAt } }

Audit Output

The audit command outputs detailed metrics for each operation:

┌──────────────────────────────────────────────────────────────┐ │ GetUser (./src/queries/user.graphql) │ ├──────────────────────────────────────────────────────────────┤ │ Depth │ 5 │ │ Aliases │ 0 │ │ Directives │ 2 │ │ Tokens │ 45 │ │ Complexity │ 12 │ └──────────────────────────────────────────────────────────────┘

Configuration

Create .graphql-inspector.yaml :

audit: documents: './src/**/*.graphql'

Thresholds for warnings

thresholds: depth: 10 aliases: 5 directives: 10 tokens: 500 complexity: 100

CI/CD Integration

GitHub Actions

name: Audit Operations user-invocable: false on: pull_request: paths: - 'src//*.graphql' - 'src//*.tsx'

jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Install Inspector
    run: npm install -g @graphql-inspector/cli

  - name: Audit operations
    run: |
      graphql-inspector audit 'src/**/*.graphql'

Audit Report

Generate a detailed report:

JSON output for processing

npx @graphql-inspector/cli audit './src/**/*.graphql' --json > audit-report.json

Human-readable output

npx @graphql-inspector/cli audit './src/**/*.graphql' 2>&1 | tee audit-report.txt

Use Cases

Pre-PR Checks

Run before creating pull requests:

Script to check operations before PR

#!/bin/bash echo "Auditing GraphQL operations..." npx @graphql-inspector/cli audit './src/**/*.graphql'

if [ $? -ne 0 ]; then echo "Warning: Some operations may have performance issues" fi

Periodic Analysis

Schedule regular audits:

GitHub Action for weekly audit

name: Weekly GraphQL Audit user-invocable: false on: schedule: - cron: '0 9 * * 1' # Monday 9am

jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: npm install -g @graphql-inspector/cli - run: graphql-inspector audit './src/**/*.graphql' --json > audit.json - name: Upload audit report uses: actions/upload-artifact@v4 with: name: graphql-audit path: audit.json

Complexity Budgets

Set limits per operation type:

Custom thresholds by operation type

audit: thresholds: queries: depth: 10 complexity: 100 mutations: depth: 5 complexity: 50 subscriptions: depth: 3 complexity: 25

Best Practices

• Regular audits - Run weekly to catch complexity creep

• Set thresholds - Define acceptable limits for your API

• Track trends - Monitor metrics over time

• Review outliers - Investigate operations with high metrics

• Optimize hot paths - Focus on frequently-used operations

• Document exceptions - Explain why complex operations are needed

• Educate team - Share audit results and best practices

• Automate alerts - Notify when thresholds are exceeded

Common Patterns

Reducing Query Depth

Before (depth 6):

query DeepQuery { user { posts { comments { author { profile { avatar } } } } } }

After (depth 3):

query FlattenedQuery { user { posts { comments { authorName authorAvatar # Denormalized field } } } }

Reducing Alias Count

Before (5 aliases):

query MultipleUsers { user1: user(id: "1") { ...UserFields } user2: user(id: "2") { ...UserFields } user3: user(id: "3") { ...UserFields } user4: user(id: "4") { ...UserFields } user5: user(id: "5") { ...UserFields } }

After (batch query):

query BatchUsers { users(ids: ["1", "2", "3", "4", "5"]) { ...UserFields } }

Troubleshooting

No operations found

• Check glob pattern matches files

• Verify files contain valid GraphQL operations

• Ensure file extensions are included

Metrics seem wrong

• Verify operation is complete

• Check for fragment definitions

• Review inline fragment usage

Audit is slow

• Limit scope with specific globs

• Exclude generated files

• Use --parallel if available

When to Use This Skill

• Performance analysis of GraphQL operations

• Identifying complex queries before production

• Setting up complexity budgets

• Regular codebase health checks

• Training developers on query optimization

• Pre-release quality gates