GraphQL profiling
Profile GraphQL queries and mutations with the nest-profiler-graphql package and inspect them in the profiler UI.
This tutorial shows how to add GraphQL profiling to a NestJS application that uses @nestjs/graphql. After completing it, every GraphQL operation will appear in /_profiler in its own GraphQL table, with a dedicated GraphQL detail tab.
Prerequisites
@eleven-labs/nest-profilerinstalled and configured@nestjs/graphqland a driver package installed (@nestjs/apollo,@nestjs/mercurius, ornestjs-graphql-yoga)
Step 1 - Install the package
pnpm add -D @eleven-labs/nest-profiler-graphqlStep 2 - Register GraphQLCollectorModule
Register GraphQLCollectorModule next to ProfilerModule in your dev-only profiling bundle:
import { Module } from '@nestjs/common';
import { ProfilerModule } from '@eleven-labs/nest-profiler';
import { GraphQLCollectorModule } from '@eleven-labs/nest-profiler-graphql';
@Module({
imports: [ProfilerModule.forRoot({ isGlobal: true }), GraphQLCollectorModule.forRoot()],
})
export class ProfilingModule {}
ProfilingModuleis the dev-only bundle loaded bymain-dev.ts— see Enabling and disabling the profiler. If the profiler is installed as a production dependency behind the runtime gate, wrap the same call inConditionalModule.registerWhen(..., isProfilerEnabled).
Your GraphQLModule stays in your own application module, free of any profiler import:
import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver } from '@nestjs/apollo';
import type { ApolloDriverConfig } from '@nestjs/apollo';
@Module({
imports: [
GraphQLModule.forRoot<ApolloDriverConfig>({
driver: ApolloDriver,
autoSchemaFile: true,
context: ({ req }) => ({ req }), // required - see Step 3
}),
],
})
export class AppModule {}Step 3 - Configure the context factory
The profiler retrieves the active HTTP profile through the GraphQL execution context. You must expose the HTTP request object in that context - the exact key depends on your driver. This is plain application config, so it ships in production unchanged:
| Driver | Key to expose | context factory |
|---|---|---|
| Apollo (Express / Fastify) | req | context: ({ req }) => ({ req }) |
| Mercurius (Fastify) | request | context: ({ request }) => ({ request }) |
| graphql-yoga (Express / Fastify) | req | context: ({ req }) => ({ req }) |
Without the context factory the profiler silently falls back to passthrough mode - GraphQL requests are still handled but not profiled.
Mercurius example
import { MercuriusDriver } from '@nestjs/mercurius';
import type { MercuriusDriverConfig } from '@nestjs/mercurius';
GraphQLModule.forRoot<MercuriusDriverConfig>({
driver: MercuriusDriver,
autoSchemaFile: true,
context: ({ request }) => ({ request }),
});Step 4 - Test it
Start your application and send a GraphQL query:
# Named query
curl -X POST http://localhost:3000/graphql \
-H "Content-Type: application/json" \
-d '{
"operationName": "GetBooks",
"query": "query GetBooks { books { id title author } }"
}'
# Query with variable
curl -X POST http://localhost:3000/graphql \
-H "Content-Type: application/json" \
-d '{
"operationName": "GetBook",
"query": "query GetBook($id: ID!) { book(id: $id) { id title author } }",
"variables": { "id": "1" }
}'
# Mutation
curl -X POST http://localhost:3000/graphql \
-H "Content-Type: application/json" \
-d '{
"operationName": "CreateBook",
"query": "mutation CreateBook($title: String!, $author: String!) { createBook(input: { title: $title, author: $author }) { id title } }",
"variables": { "title": "NestJS in Action", "author": "John Doe" }
}'Open /_profiler to see the captured profiles. GraphQL operations are listed in their own GraphQL table (separate from REST requests), each row showing the operation type (QUERY / MUTATION / SUBSCRIPTION) and the operation or field name. The table has its own filter bar - the universal filters (search, status, duration…) plus an Operation filter to narrow by operation type.
Open an operation to land on its dedicated GraphQL detail tab, which displays:
- Operation type badge (Query / Mutation / Subscription)
- Operation name - if provided in the request
- Field name - the entry-point resolver field
- Query - the full document, syntax-highlighted
- Variables - the variables object, syntax-highlighted as JSON
- Response - the
{ data, errors }envelope returned to the client - Request headers - the underlying HTTP headers
GraphQL errors returned with an HTTP 200 are still surfaced in the Exceptions tab.
Field resolvers - one operation, several collectors
A GraphQL operation is a single profile, whatever the resolvers do underneath. Field resolvers run after the root resolver has returned, and collection is deferred until the response is sent - so one query that lists products (SQL), resolves each product's reviews (MongoDB) and then each review's author (outgoing HTTP) fills three collector panels in the same profile, with the Execution Trace interleaving their spans.
query Products {
products {
# 1. SQL catalog - root resolver
id
name
reviews {
# 2. MongoDB - field resolver
rating
author {
# 3. HTTP - nested field resolver
name
company
}
}
}
}That shape is also where GraphQL's classic N+1 lives: one query per product, then one HTTP call per review. The rule engine tags the repeats in both the MongoDB and HTTP Client panels - see Performance tags. Batching them behind request-scoped DataLoaders collapses each side into a single call; the example application runs the very same query either way behind a flag, so the two waterfalls can be compared profile to profile.
Filtering playground and introspection requests
By default, Apollo Sandbox (GET /graphql) and introspection queries are profiled. Use the pre-built filters to exclude them:
import { ProfilerModule, combineFilters } from '@eleven-labs/nest-profiler';
import {
GraphQLCollectorModule,
ignoreGraphQLPlayground,
ignoreGraphQLIntrospection,
} from '@eleven-labs/nest-profiler-graphql';
ProfilerModule.forRoot({
isGlobal: true,
ignoreRequest: combineFilters(ignoreGraphQLPlayground, ignoreGraphQLIntrospection),
}),
GraphQLCollectorModule.forRoot(),| Filter | What it skips |
|---|---|
ignoreGraphQLPlayground | GET /graphql with Accept: text/html - the Sandbox page load |
ignoreGraphQLIntrospection | Any POST with operationName: IntrospectionQuery or a query referencing __schema / __type |
GraphQL errors in the Exceptions tab
GraphQL-level errors - schema validation failures and resolver errors returned in response.body.errors - appear in the Exceptions tab with an amber GraphQLError badge. They are visually distinct from NestJS runtime exceptions, which use a red badge.
This means you can inspect them even when Apollo returns an HTTP 200 with an errors array (the standard GraphQL error behaviour).
How it works
GraphQLCollectorModule registers a GraphQLContextAdapter and a graphql entrypoint type: for each GraphQL request it recovers the profile the HTTP middleware already created, captures the operation metadata, and flips entrypoint.type from http to graphql so it routes to the dedicated GraphQL list view and detail tab. See How it works on the package page.
@eleven-labs/nest-profiler-graphql is the reference implementation of the IContextAdapter pattern from @eleven-labs/nest-profiler. You can use the same pattern to profile gRPC, Kafka, WebSockets, or any other NestJS execution context - see the custom protocol adapters section.