Package graphql.execution.instrumentation

Interface Instrumentation

All Known Implementing Classes:

ChainedInstrumentation, FieldValidationInstrumentation, MaxQueryComplexityInstrumentation, MaxQueryDepthInstrumentation, NoContextChainedInstrumentation, SimpleInstrumentation, SimplePerformantInstrumentation, TracingInstrumentation

@PublicSpi
public interface Instrumentation

Provides the capability to instrument the execution steps of a GraphQL query.

For example you might want to track which fields are taking the most time to fetch from the backing database or log what fields are being asked for.

Remember that graphql calls can cross threads so make sure you think about the thread safety of any instrumentation code when you are writing it.

Each step gives back an InstrumentationContext object. This has two callbacks on it, one for the step is `dispatched` and one for when the step has `completed`. This is done because many of the "steps" are asynchronous operations such as fetching data and resolving it into objects.

Method Summary

Modifier and Type	Method	Description
default InstrumentationContext<Object>	beginDeferredField(InstrumentationFieldParameters parameters, InstrumentationState state)	This is called just before a deferred field is resolved into a value.
default @Nullable ExecuteObjectInstrumentationContext	beginExecuteObject(InstrumentationExecutionStrategyParameters parameters, InstrumentationState state)	This is called each time an ExecutionStrategy object resolution is called, which may be multiple times per query as the engine recursively descends over the query.
default @Nullable InstrumentationContext<ExecutionResult>	beginExecuteOperation(InstrumentationExecuteOperationParameters parameters, InstrumentationState state)	This is called just before the execution of the query operation is started.
default @Nullable InstrumentationContext<ExecutionResult>	beginExecution(InstrumentationExecutionParameters parameters, InstrumentationState state)	This is called right at the start of query execution, and it's the first step in the instrumentation chain.
default @Nullable ExecutionStrategyInstrumentationContext	beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters, InstrumentationState state)	This is called each time an ExecutionStrategy is invoked, which may be multiple times per query as the engine recursively descends over the query.
default @Nullable InstrumentationContext<Object>	beginFieldCompletion(InstrumentationFieldCompleteParameters parameters, InstrumentationState state)	This is called just before the complete field is started.
default @Nullable InstrumentationContext<Object>	beginFieldExecution(InstrumentationFieldParameters parameters, InstrumentationState state)	This is called just before a field is resolved into a value.
default @Nullable InstrumentationContext<Object>	beginFieldFetch(InstrumentationFieldFetchParameters parameters, InstrumentationState state)	Deprecated. use beginFieldFetching(InstrumentationFieldFetchParameters, InstrumentationState) instead
default @Nullable FieldFetchingInstrumentationContext	beginFieldFetching(InstrumentationFieldFetchParameters parameters, InstrumentationState state)	This is called just before a field DataFetcher is invoked.
default @Nullable InstrumentationContext<Object>	beginFieldListCompletion(InstrumentationFieldCompleteParameters parameters, InstrumentationState state)	This is called just before the complete field list is started.
default @Nullable InstrumentationContext<Document>	beginParse(InstrumentationExecutionParameters parameters, InstrumentationState state)	This is called just before a query is parsed.
default @Nullable InstrumentationContext<Void>	beginReactiveResults(InstrumentationReactiveResultsParameters parameters, InstrumentationState state)	This is called just before the execution of any reactive results, namely incremental deferred results or subscriptions.
default @Nullable InstrumentationContext<ExecutionResult>	beginSubscribedFieldEvent(InstrumentationFieldParameters parameters, InstrumentationState state)	This is called each time a subscription field produces a new reactive stream event value and it needs to be mapped over via the graphql field subselection.
default @Nullable InstrumentationContext<List<ValidationError>>	beginValidation(InstrumentationValidationParameters parameters, InstrumentationState state)	This is called just before the parsed query document is validated.
default @Nullable InstrumentationState	createState(InstrumentationCreateStateParameters parameters)	This method is retained for backwards compatibility reasons so that previous Instrumentation implementations continue to work.
default @Nullable CompletableFuture<InstrumentationState>	createStateAsync(InstrumentationCreateStateParameters parameters)	This will be called just before execution to create an object, in an asynchronous manner, that is given back to all instrumentation methods to allow them to have per execution request state
default @NonNull DataFetcher<?>	instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters, InstrumentationState state)	This is called to instrument a DataFetcher just before it is used to fetch a field, allowing you to adjust what information is passed back or record information about specific data fetches.
default @NonNull DocumentAndVariables	instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables, InstrumentationExecutionParameters parameters, InstrumentationState state)	This is called to instrument a Document and variables before it is used allowing you to adjust the query AST if you so desire
default @NonNull ExecutionContext	instrumentExecutionContext(ExecutionContext executionContext, InstrumentationExecutionParameters parameters, InstrumentationState state)	This is called to instrument a ExecutionContext before it is used to execute a query, allowing you to adjust the base data used.
default @NonNull ExecutionInput	instrumentExecutionInput(ExecutionInput executionInput, InstrumentationExecutionParameters parameters, InstrumentationState state)	This is called to instrument a ExecutionInput before it is used to parse, validate and execute a query, allowing you to adjust what query input parameters are used
default @NonNull CompletableFuture<ExecutionResult>	instrumentExecutionResult(ExecutionResult executionResult, InstrumentationExecutionParameters parameters, InstrumentationState state)	This is called to allow instrumentation to instrument the execution result in some way
default @NonNull GraphQLSchema	instrumentSchema(GraphQLSchema schema, InstrumentationExecutionParameters parameters, InstrumentationState state)	This is called to instrument a GraphQLSchema before it is used to parse, validate and execute a query, allowing you to adjust what types are used.

Method Details

createStateAsync

default @Nullable CompletableFuture<InstrumentationState> createStateAsync(InstrumentationCreateStateParameters parameters)

This will be called just before execution to create an object, in an asynchronous manner, that is given back to all instrumentation methods to allow them to have per execution request state

Parameters:

parameters - the parameters to this step

Returns:

a state object that is passed to each method

createState

default @Nullable InstrumentationState createState(InstrumentationCreateStateParameters parameters)

This method is retained for backwards compatibility reasons so that previous Instrumentation implementations continue to work. The graphql-java code only called createStateAsync(InstrumentationCreateStateParameters) but the default implementation calls back to this method.

Parameters:

parameters - the parameters to this step

Returns:

a state object that is passed to each method

beginExecution

default @Nullable InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters,
 InstrumentationState state)

This is called right at the start of query execution, and it's the first step in the instrumentation chain.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginParse

default @Nullable InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters,
 InstrumentationState state)

This is called just before a query is parsed.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginValidation

default @Nullable InstrumentationContext<List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters,
 InstrumentationState state)

This is called just before the parsed query document is validated.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginExecuteOperation

default @Nullable InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters,
 InstrumentationState state)

This is called just before the execution of the query operation is started.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginReactiveResults

default @Nullable InstrumentationContext<Void> beginReactiveResults(InstrumentationReactiveResultsParameters parameters,
 InstrumentationState state)

This is called just before the execution of any reactive results, namely incremental deferred results or subscriptions. When the Publisher finally ends (with either a Throwable or none) then the InstrumentationContext wil be called back to say the reactive results have finished.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginExecutionStrategy

default @Nullable ExecutionStrategyInstrumentationContext beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters,
 InstrumentationState state)

This is called each time an ExecutionStrategy is invoked, which may be multiple times per query as the engine recursively descends over the query.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable ExecutionStrategyInstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginExecuteObject

default @Nullable ExecuteObjectInstrumentationContext beginExecuteObject(InstrumentationExecutionStrategyParameters parameters,
 InstrumentationState state)

This is called each time an ExecutionStrategy object resolution is called, which may be multiple times per query as the engine recursively descends over the query.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable ExecutionStrategyInstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginDeferredField

@ExperimentalApi
default InstrumentationContext<Object> beginDeferredField(InstrumentationFieldParameters parameters,
 InstrumentationState state)

This is called just before a deferred field is resolved into a value.

This is an EXPERIMENTAL instrumentation callback. The method signature will definitely change.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginSubscribedFieldEvent

default @Nullable InstrumentationContext<ExecutionResult> beginSubscribedFieldEvent(InstrumentationFieldParameters parameters,
 InstrumentationState state)

This is called each time a subscription field produces a new reactive stream event value and it needs to be mapped over via the graphql field subselection.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginFieldExecution

default @Nullable InstrumentationContext<Object> beginFieldExecution(InstrumentationFieldParameters parameters,
 InstrumentationState state)

This is called just before a field is resolved into a value.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginFieldFetch

@Deprecated(since="2024-04-18")
default @Nullable InstrumentationContext<Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters,
 InstrumentationState state)

Deprecated.

use beginFieldFetching(InstrumentationFieldFetchParameters, InstrumentationState) instead

This is called just before a field DataFetcher is invoked.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginFieldFetching

default @Nullable FieldFetchingInstrumentationContext beginFieldFetching(InstrumentationFieldFetchParameters parameters,
 InstrumentationState state)

This is called just before a field DataFetcher is invoked. The FieldFetchingInstrumentationContext.onFetchedValue(Object) callback will be invoked once a value is returned by a DataFetcher but perhaps before its value is completed if it's a CompletableFuture value.

This method is the replacement method for the now deprecated beginFieldFetch(InstrumentationFieldFetchParameters, InstrumentationState) method, and it should be implemented in new Instrumentation classes. This default version of this method calls back to the deprecated beginFieldFetch(InstrumentationFieldFetchParameters, InstrumentationState) method so that older implementations continue to work.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginFieldCompletion

default @Nullable InstrumentationContext<Object> beginFieldCompletion(InstrumentationFieldCompleteParameters parameters,
 InstrumentationState state)

This is called just before the complete field is started.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

beginFieldListCompletion

default @Nullable InstrumentationContext<Object> beginFieldListCompletion(InstrumentationFieldCompleteParameters parameters,
 InstrumentationState state)

This is called just before the complete field list is started.

Parameters:

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a nullable InstrumentationContext object that will be called back when the step ends (assuming it's not null)

instrumentExecutionInput

default @NonNull ExecutionInput instrumentExecutionInput(ExecutionInput executionInput,
 InstrumentationExecutionParameters parameters,
 InstrumentationState state)

This is called to instrument a ExecutionInput before it is used to parse, validate and execute a query, allowing you to adjust what query input parameters are used

Parameters:

executionInput - the execution input to be used

parameters - the parameters describing the field to be fetched

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a non-null instrumented ExecutionInput, the default is to return to the same object

instrumentDocumentAndVariables

default @NonNull DocumentAndVariables instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables,
 InstrumentationExecutionParameters parameters,
 InstrumentationState state)

This is called to instrument a Document and variables before it is used allowing you to adjust the query AST if you so desire

Parameters:

documentAndVariables - the document and variables to be used

parameters - the parameters describing the execution

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a non-null instrumented DocumentAndVariables, the default is to return to the same objects

instrumentSchema

default @NonNull GraphQLSchema instrumentSchema(GraphQLSchema schema,
 InstrumentationExecutionParameters parameters,
 InstrumentationState state)

This is called to instrument a GraphQLSchema before it is used to parse, validate and execute a query, allowing you to adjust what types are used.

Parameters:

schema - the schema to be used

parameters - the parameters describing the field to be fetched

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a non-null instrumented GraphQLSchema, the default is to return to the same object

instrumentExecutionContext

default @NonNull ExecutionContext instrumentExecutionContext(ExecutionContext executionContext,
 InstrumentationExecutionParameters parameters,
 InstrumentationState state)

This is called to instrument a ExecutionContext before it is used to execute a query, allowing you to adjust the base data used.

Parameters:

executionContext - the execution context to be used

parameters - the parameters describing the field to be fetched

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a non-null instrumented ExecutionContext, the default is to return to the same object

instrumentDataFetcher

default @NonNull DataFetcher<?> instrumentDataFetcher(DataFetcher<?> dataFetcher,
 InstrumentationFieldFetchParameters parameters,
 InstrumentationState state)

This is called to instrument a DataFetcher just before it is used to fetch a field, allowing you to adjust what information is passed back or record information about specific data fetches. Note the same data fetcher instance maybe presented to you many times and that data fetcher implementations widely vary.

Parameters:

dataFetcher - the data fetcher about to be used

parameters - the parameters describing the field to be fetched

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a non-null instrumented DataFetcher, the default is to return to the same object

instrumentExecutionResult

default @NonNull CompletableFuture<ExecutionResult> instrumentExecutionResult(ExecutionResult executionResult,
 InstrumentationExecutionParameters parameters,
 InstrumentationState state)

This is called to allow instrumentation to instrument the execution result in some way

Parameters:

executionResult - CompletableFuture of the result to instrument

parameters - the parameters to this step

state - the state created during the call to createStateAsync(InstrumentationCreateStateParameters)

Returns:

a new execution result completable future