Overview

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

bash

# 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

bash

# 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:

graphql

# 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:

graphql

# 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:

graphql

# 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:

graphql

# 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:

yaml

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

  # Thresholds for warnings
  thresholds:
    depth: 10
    aliases: 5
    directives: 10
    tokens: 500
    complexity: 100

CI/CD Integration

GitHub Actions

yaml

name: Audit Operations
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:

bash

# 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:

bash

# 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:

yaml

# GitHub Action for weekly audit
name: Weekly GraphQL Audit
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:

yaml

# 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):

graphql

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

After (depth 3):

graphql

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

Reducing Alias Count

Before (5 aliases):

graphql

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):

graphql

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

📖 graphql-inspector-audit

Overview

Overview

Core Commands

Basic Audit

Audit with Schema

Metrics Analyzed

Query Depth

Alias Count

Directive Count

Token Count

Audit Output

Configuration

CI/CD Integration

GitHub Actions

Audit Report

Use Cases

Pre-PR Checks

Periodic Analysis

Complexity Budgets

Best Practices

Common Patterns

Reducing Query Depth

Reducing Alias Count

Troubleshooting

No operations found

Metrics seem wrong

Audit is slow

When to Use This Skill