graphql-java · dondonz · Jul 21, 2025 · May 19, 2025 · May 19, 2025 · May 20, 2025
diff --git a/src/main/java/graphql/EngineRunningState.java b/src/main/java/graphql/EngineRunningState.java
@@ -39,13 +39,18 @@ public class EngineRunningState {
 
     private final AtomicInteger isRunning = new AtomicInteger(0);
 
-    public EngineRunningState(ExecutionInput executionInput) {
+
+    public EngineRunningState(ExecutionInput executionInput, Profiler profiler) {
+        EngineRunningObserver engineRunningObserver = executionInput.getGraphQLContext().get(EngineRunningObserver.ENGINE_RUNNING_OBSERVER_KEY);
+        EngineRunningObserver wrappedObserver = profiler.wrapEngineRunningObserver(engineRunningObserver);
+        this.engineRunningObserver = wrappedObserver;
         this.executionInput = executionInput;
         this.graphQLContext = executionInput.getGraphQLContext();
         this.executionId = executionInput.getExecutionId();
-        this.engineRunningObserver = executionInput.getGraphQLContext().get(EngineRunningObserver.ENGINE_RUNNING_OBSERVER_KEY);
     }
 
+
+
     public <U, T> CompletableFuture<U> handle(CompletableFuture<T> src, BiFunction<? super T, Throwable, ? extends U> fn) {
         if (engineRunningObserver == null) {
             return src.handle(fn);

diff --git a/src/main/java/graphql/ExecutionInput.java b/src/main/java/graphql/ExecutionInput.java
@@ -34,6 +34,7 @@ public class ExecutionInput {
     private final ExecutionId executionId;
     private final Locale locale;
     private final AtomicBoolean cancelled;
+    private final boolean profileExecution;
 
 
     @Internal
@@ -50,6 +51,7 @@ private ExecutionInput(Builder builder) {
         this.localContext = builder.localContext;
         this.extensions = builder.extensions;
         this.cancelled = builder.cancelled;
+        this.profileExecution = builder.profileExecution;
     }
 
     /**
@@ -186,6 +188,11 @@ public void cancel() {
         cancelled.set(true);
     }
 
+
+    public boolean isProfileExecution() {
+        return profileExecution;
+    }
+
     /**
      * This helps you transform the current ExecutionInput object into another one by starting a builder with all
      * the current values and allows you to transform it how you want.
@@ -266,6 +273,7 @@ public static class Builder {
         private Locale locale = Locale.getDefault();
         private ExecutionId executionId;
         private AtomicBoolean cancelled = new AtomicBoolean(false);
+        private boolean profileExecution;
 
         /**
          * Package level access to the graphql context
@@ -414,6 +422,11 @@ public Builder dataLoaderRegistry(DataLoaderRegistry dataLoaderRegistry) {
             return this;
         }
 
+        public Builder profileExecution(boolean profileExecution) {
+            this.profileExecution = profileExecution;
+            return this;
+        }
+
         public ExecutionInput build() {
             return new ExecutionInput(this);
         }

diff --git a/src/main/java/graphql/GraphQL.java b/src/main/java/graphql/GraphQL.java
@@ -9,7 +9,6 @@
 import graphql.execution.ExecutionId;
 import graphql.execution.ExecutionIdProvider;
 import graphql.execution.ExecutionStrategy;
-import graphql.execution.ResponseMapFactory;
 import graphql.execution.SimpleDataFetcherExceptionHandler;
 import graphql.execution.SubscriptionExecutionStrategy;
 import graphql.execution.ValueUnboxer;
@@ -27,10 +26,11 @@
 import graphql.language.Document;
 import graphql.schema.GraphQLSchema;
 import graphql.validation.ValidationError;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 
 import java.util.List;
 import java.util.Locale;
-import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
 import java.util.concurrent.atomic.AtomicReference;
@@ -83,6 +83,7 @@
  */
 @SuppressWarnings("Duplicates")
 @PublicApi
+@NullMarked
 public class GraphQL {
 
     /**
@@ -259,16 +260,17 @@ public GraphQL transform(Consumer<GraphQL.Builder> builderConsumer) {
                 .queryExecutionStrategy(this.queryStrategy)
                 .mutationExecutionStrategy(this.mutationStrategy)
                 .subscriptionExecutionStrategy(this.subscriptionStrategy)
-                .executionIdProvider(Optional.ofNullable(this.idProvider).orElse(builder.idProvider))
-                .instrumentation(Optional.ofNullable(this.instrumentation).orElse(builder.instrumentation))
-                .preparsedDocumentProvider(Optional.ofNullable(this.preparsedDocumentProvider).orElse(builder.preparsedDocumentProvider));
+                .executionIdProvider(this.idProvider)
+                .instrumentation(this.instrumentation)
+                .preparsedDocumentProvider(this.preparsedDocumentProvider);
 
         builderConsumer.accept(builder);
 
         return builder.build();
     }
 
     @PublicApi
+    @NullUnmarked
     public static class Builder {
         private GraphQLSchema graphQLSchema;
         private ExecutionStrategy queryExecutionStrategy;
@@ -478,9 +480,11 @@ public CompletableFuture<ExecutionResult> executeAsync(UnaryOperator<ExecutionIn
      * @return a promise to an {@link ExecutionResult} which can include errors
      */
     public CompletableFuture<ExecutionResult> executeAsync(ExecutionInput executionInput) {
-        EngineRunningState engineRunningState = new EngineRunningState(executionInput);
+        Profiler profiler = executionInput.isProfileExecution() ? new ProfilerImpl(executionInput.getGraphQLContext()) : Profiler.NO_OP;
+        EngineRunningState engineRunningState = new EngineRunningState(executionInput, profiler);
         return engineRunningState.engineRun(() -> {
             ExecutionInput executionInputWithId = ensureInputHasId(executionInput);
+            profiler.setExecutionInputAndInstrumentation(executionInputWithId, instrumentation);
             engineRunningState.updateExecutionInput(executionInputWithId);
 
             CompletableFuture<InstrumentationState> instrumentationStateCF = instrumentation.createStateAsync(new InstrumentationCreateStateParameters(this.graphQLSchema, executionInputWithId));
@@ -497,7 +501,7 @@ public CompletableFuture<ExecutionResult> executeAsync(ExecutionInput executionI
 
                     GraphQLSchema graphQLSchema = instrumentation.instrumentSchema(this.graphQLSchema, instrumentationParameters, instrumentationState);
 
-                    CompletableFuture<ExecutionResult> executionResult = parseValidateAndExecute(instrumentedExecutionInput, graphQLSchema, instrumentationState, engineRunningState);
+                    CompletableFuture<ExecutionResult> executionResult = parseValidateAndExecute(instrumentedExecutionInput, graphQLSchema, instrumentationState, engineRunningState, profiler);
                     //
                     // finish up instrumentation
                     executionResult = executionResult.whenComplete(completeInstrumentationCtxCF(executionInstrumentation));
@@ -529,7 +533,7 @@ private ExecutionInput ensureInputHasId(ExecutionInput executionInput) {
     }
 
 
-    private CompletableFuture<ExecutionResult> parseValidateAndExecute(ExecutionInput executionInput, GraphQLSchema graphQLSchema, InstrumentationState instrumentationState, EngineRunningState engineRunningState) {
+    private CompletableFuture<ExecutionResult> parseValidateAndExecute(ExecutionInput executionInput, GraphQLSchema graphQLSchema, InstrumentationState instrumentationState, EngineRunningState engineRunningState, Profiler profiler) {
         AtomicReference<ExecutionInput> executionInputRef = new AtomicReference<>(executionInput);
         Function<ExecutionInput, PreparsedDocumentEntry> computeFunction = transformedInput -> {
             // if they change the original query in the pre-parser, then we want to see it downstream from then on
@@ -542,7 +546,7 @@ private CompletableFuture<ExecutionResult> parseValidateAndExecute(ExecutionInpu
                 return CompletableFuture.completedFuture(new ExecutionResultImpl(preparsedDocumentEntry.getErrors()));
             }
             try {
-                return execute(executionInputRef.get(), preparsedDocumentEntry.getDocument(), graphQLSchema, instrumentationState, engineRunningState);
+                return execute(Assert.assertNotNull(executionInputRef.get()), preparsedDocumentEntry.getDocument(), graphQLSchema, instrumentationState, engineRunningState, profiler);
             } catch (AbortExecutionException e) {
                 return CompletableFuture.completedFuture(e.toExecutionResult());
             }
@@ -551,7 +555,7 @@ private CompletableFuture<ExecutionResult> parseValidateAndExecute(ExecutionInpu
 
     private PreparsedDocumentEntry parseAndValidate(AtomicReference<ExecutionInput> executionInputRef, GraphQLSchema graphQLSchema, InstrumentationState instrumentationState) {
 
-        ExecutionInput executionInput = executionInputRef.get();
+        ExecutionInput executionInput = assertNotNull(executionInputRef.get());
 
         ParseAndValidateResult parseResult = parse(executionInput, graphQLSchema, instrumentationState);
         if (parseResult.isFailure()) {
@@ -606,13 +610,14 @@ private CompletableFuture<ExecutionResult> execute(ExecutionInput executionInput
                                                        Document document,
                                                        GraphQLSchema graphQLSchema,
                                                        InstrumentationState instrumentationState,
-                                                       EngineRunningState engineRunningState
+                                                       EngineRunningState engineRunningState,
+                                                       Profiler profiler
     ) {
 
         Execution execution = new Execution(queryStrategy, mutationStrategy, subscriptionStrategy, instrumentation, valueUnboxer, doNotAutomaticallyDispatchDataLoader);
         ExecutionId executionId = executionInput.getExecutionId();
 
-        return execution.execute(document, graphQLSchema, executionId, executionInput, instrumentationState, engineRunningState);
+        return execution.execute(document, graphQLSchema, executionId, executionInput, instrumentationState, engineRunningState, profiler);
     }
 
 }
diff --git a/src/main/java/graphql/Profiler.java b/src/main/java/graphql/Profiler.java
@@ -0,0 +1,59 @@
+package graphql;
+
+import graphql.execution.EngineRunningObserver;
+import graphql.execution.ResultPath;
+import graphql.execution.instrumentation.Instrumentation;
+import graphql.language.OperationDefinition;
+import graphql.schema.DataFetcher;
+import graphql.schema.GraphQLFieldDefinition;
+import graphql.schema.GraphQLOutputType;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+@Internal
+@NullMarked
+public interface Profiler {
+
+
+    Profiler NO_OP = new Profiler() {
+    };
+
+
+    default void setExecutionInputAndInstrumentation(ExecutionInput executionInput, Instrumentation instrumentation) {
+
+    }
+
+    default void dataLoaderUsed(String dataLoaderName) {
+
+
+    }
+
+    default void fieldFetched(Object fetchedObject, DataFetcher<?> originalDataFetcher, DataFetcher<?> dataFetcher, ResultPath path, GraphQLFieldDefinition fieldDef, GraphQLOutputType parentType) {
+
+    }
+
+    default @Nullable EngineRunningObserver wrapEngineRunningObserver(@Nullable EngineRunningObserver engineRunningObserver) {
+        return engineRunningObserver;
+    }
+
+    default void operationDefinition(OperationDefinition operationDefinition) {
+
+    }
+
+    default void oldStrategyDispatchingAll(int level) {
+
+    }
+
+    default void batchLoadedOldStrategy(String name, int level, int count) {
+
+
+    }
+
+    default void batchLoadedNewStrategy(String dataLoaderName, @Nullable Integer level, int count) {
+
+    }
+
+    default <V> void manualDispatch(String dataLoaderName, int level, int count) {
+
+    }
+}