Interface Instrumentation
-
- All Known Implementing Classes:
ChainedInstrumentation
,DataLoaderDispatcherInstrumentation
,ExecutorInstrumentation
,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
All Methods Instance Methods Default Methods Deprecated Methods Modifier and Type Method Description default @NotNull InstrumentationContext<ExecutionResult>
beginExecuteOperation(InstrumentationExecuteOperationParameters parameters)
Deprecated.default @Nullable InstrumentationContext<ExecutionResult>
beginExecuteOperation(InstrumentationExecuteOperationParameters parameters, InstrumentationState state)
This is called just before the execution of the query operation is started.default @NotNull InstrumentationContext<ExecutionResult>
beginExecution(InstrumentationExecutionParameters parameters)
Deprecated.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 @NotNull ExecutionStrategyInstrumentationContext
beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters)
Deprecated.default @Nullable ExecutionStrategyInstrumentationContext
beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters, InstrumentationState state)
This is called each time anExecutionStrategy
is invoked, which may be multiple times per query as the engine recursively descends down over the query.default @NotNull InstrumentationContext<ExecutionResult>
beginField(InstrumentationFieldParameters parameters)
Deprecated.default @Nullable InstrumentationContext<ExecutionResult>
beginField(InstrumentationFieldParameters parameters, InstrumentationState state)
This is called just before a field is resolved into a value.default @NotNull InstrumentationContext<ExecutionResult>
beginFieldComplete(InstrumentationFieldCompleteParameters parameters)
Deprecated.default @Nullable InstrumentationContext<ExecutionResult>
beginFieldComplete(InstrumentationFieldCompleteParameters parameters, InstrumentationState state)
This is called just before the complete field is started.default @NotNull InstrumentationContext<java.lang.Object>
beginFieldFetch(InstrumentationFieldFetchParameters parameters)
Deprecated.default @Nullable InstrumentationContext<java.lang.Object>
beginFieldFetch(InstrumentationFieldFetchParameters parameters, InstrumentationState state)
This is called just before a fieldDataFetcher
is invoked.default @NotNull InstrumentationContext<ExecutionResult>
beginFieldListComplete(InstrumentationFieldCompleteParameters parameters)
Deprecated.default @Nullable InstrumentationContext<ExecutionResult>
beginFieldListComplete(InstrumentationFieldCompleteParameters parameters, InstrumentationState state)
This is called just before the complete field list is started.default @NotNull InstrumentationContext<Document>
beginParse(InstrumentationExecutionParameters parameters)
Deprecated.default @Nullable InstrumentationContext<Document>
beginParse(InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called just before a query is parsed.default @NotNull InstrumentationContext<ExecutionResult>
beginSubscribedFieldEvent(InstrumentationFieldParameters parameters)
Deprecated.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 @NotNull InstrumentationContext<java.util.List<ValidationError>>
beginValidation(InstrumentationValidationParameters parameters)
Deprecated.default @Nullable InstrumentationContext<java.util.List<ValidationError>>
beginValidation(InstrumentationValidationParameters parameters, InstrumentationState state)
This is called just before the parsed query document is validated.default InstrumentationState
createState()
Deprecated.default @Nullable InstrumentationState
createState(InstrumentationCreateStateParameters parameters)
Deprecated.default @Nullable java.util.concurrent.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 statedefault @NotNull DataFetcher<?>
instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters)
Deprecated.default @NotNull DataFetcher<?>
instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters, InstrumentationState state)
This is called to instrument aDataFetcher
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 @NotNull DocumentAndVariables
instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables, InstrumentationExecutionParameters parameters)
default @NotNull DocumentAndVariables
instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to instrument aDocument
and variables before it is used allowing you to adjust the query AST if you so desiredefault @NotNull ExecutionContext
instrumentExecutionContext(ExecutionContext executionContext, InstrumentationExecutionParameters parameters)
default @NotNull ExecutionContext
instrumentExecutionContext(ExecutionContext executionContext, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to instrument aExecutionContext
before it is used to execute a query, allowing you to adjust the base data used.default @NotNull ExecutionInput
instrumentExecutionInput(ExecutionInput executionInput, InstrumentationExecutionParameters parameters)
default @NotNull ExecutionInput
instrumentExecutionInput(ExecutionInput executionInput, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to instrument aExecutionInput
before it is used to parse, validate and execute a query, allowing you to adjust what query input parameters are useddefault @NotNull java.util.concurrent.CompletableFuture<ExecutionResult>
instrumentExecutionResult(ExecutionResult executionResult, InstrumentationExecutionParameters parameters)
default @NotNull java.util.concurrent.CompletableFuture<ExecutionResult>
instrumentExecutionResult(ExecutionResult executionResult, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to allow instrumentation to instrument the execution result in some waydefault @NotNull GraphQLSchema
instrumentSchema(GraphQLSchema schema, InstrumentationExecutionParameters parameters)
Deprecated.default @NotNull GraphQLSchema
instrumentSchema(GraphQLSchema schema, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to instrument aGraphQLSchema
before it is used to parse, validate and execute a query, allowing you to adjust what types are used.
-
-
-
Method Detail
-
createState
@Deprecated default InstrumentationState createState()
Deprecated.This will be called just before execution to create an object that is given back to all instrumentation methods to allow them to have per execution request state- Returns:
- a state object that is passed to each method
-
createState
@Deprecated @Nullable default @Nullable InstrumentationState createState(InstrumentationCreateStateParameters parameters)
Deprecated.This will be called just before execution to create an object 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
-
createStateAsync
@Nullable default @Nullable java.util.concurrent.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
-
beginExecution
@Deprecated @NotNull default @NotNull InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters)
Deprecated.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- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginExecution
@Nullable 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 stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginParse
@Deprecated @NotNull default @NotNull InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters)
Deprecated.This is called just before a query is parsed.- Parameters:
parameters
- the parameters to this step- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginParse
@Nullable default @Nullable InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called just before a query is parsed.- Parameters:
parameters
- the parameters to this stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginValidation
@Deprecated @NotNull default @NotNull InstrumentationContext<java.util.List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters)
Deprecated.This is called just before the parsed query document is validated.- Parameters:
parameters
- the parameters to this step- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginValidation
@Nullable default @Nullable InstrumentationContext<java.util.List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters, InstrumentationState state)
This is called just before the parsed query document is validated.- Parameters:
parameters
- the parameters to this stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginExecuteOperation
@Deprecated @NotNull default @NotNull InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters)
Deprecated.This is called just before the execution of the query operation is started.- Parameters:
parameters
- the parameters to this step- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginExecuteOperation
@Nullable 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 stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginExecutionStrategy
@Deprecated @NotNull default @NotNull ExecutionStrategyInstrumentationContext beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters)
Deprecated.This is called each time anExecutionStrategy
is invoked, which may be multiple times per query as the engine recursively descends down over the query.- Parameters:
parameters
- the parameters to this step- Returns:
- a non null
ExecutionStrategyInstrumentationContext
object that will be called back when the step ends
-
beginExecutionStrategy
@Nullable default @Nullable ExecutionStrategyInstrumentationContext beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters, InstrumentationState state)
This is called each time anExecutionStrategy
is invoked, which may be multiple times per query as the engine recursively descends down over the query.- Parameters:
parameters
- the parameters to this stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
ExecutionStrategyInstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginSubscribedFieldEvent
@Deprecated @NotNull default @NotNull InstrumentationContext<ExecutionResult> beginSubscribedFieldEvent(InstrumentationFieldParameters parameters)
Deprecated.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- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginSubscribedFieldEvent
@Nullable 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 stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginField
@Deprecated @NotNull default @NotNull InstrumentationContext<ExecutionResult> beginField(InstrumentationFieldParameters parameters)
Deprecated.This is called just before a field is resolved into a value.- Parameters:
parameters
- the parameters to this step- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginField
@Nullable default @Nullable InstrumentationContext<ExecutionResult> beginField(InstrumentationFieldParameters parameters, InstrumentationState state)
This is called just before a field is resolved into a value.- Parameters:
parameters
- the parameters to this stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginFieldFetch
@Deprecated @NotNull default @NotNull InstrumentationContext<java.lang.Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters)
Deprecated.This is called just before a fieldDataFetcher
is invoked.- Parameters:
parameters
- the parameters to this step- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginFieldFetch
@Nullable default @Nullable InstrumentationContext<java.lang.Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters, InstrumentationState state)
This is called just before a fieldDataFetcher
is invoked.- Parameters:
parameters
- the parameters to this stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginFieldComplete
@Deprecated @NotNull default @NotNull InstrumentationContext<ExecutionResult> beginFieldComplete(InstrumentationFieldCompleteParameters parameters)
Deprecated.This is called just before the complete field is started.- Parameters:
parameters
- the parameters to this step- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginFieldComplete
@Nullable default @Nullable InstrumentationContext<ExecutionResult> beginFieldComplete(InstrumentationFieldCompleteParameters parameters, InstrumentationState state)
This is called just before the complete field is started.- Parameters:
parameters
- the parameters to this stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
beginFieldListComplete
@Deprecated @NotNull default @NotNull InstrumentationContext<ExecutionResult> beginFieldListComplete(InstrumentationFieldCompleteParameters parameters)
Deprecated.This is called just before the complete field list is started.- Parameters:
parameters
- the parameters to this step- Returns:
- a non null
InstrumentationContext
object that will be called back when the step ends
-
beginFieldListComplete
@Nullable default @Nullable InstrumentationContext<ExecutionResult> beginFieldListComplete(InstrumentationFieldCompleteParameters parameters, InstrumentationState state)
This is called just before the complete field list is started.- Parameters:
parameters
- the parameters to this stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a nullable
InstrumentationContext
object that will be called back when the step ends (assuming it's not null)
-
instrumentExecutionInput
@Deprecated @NotNull default @NotNull ExecutionInput instrumentExecutionInput(ExecutionInput executionInput, InstrumentationExecutionParameters parameters)
Deprecated.This is called to instrument aExecutionInput
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 usedparameters
- the parameters describing the field to be fetched- Returns:
- a non null instrumented ExecutionInput, the default is to return to the same object
-
instrumentExecutionInput
@NotNull default @NotNull ExecutionInput instrumentExecutionInput(ExecutionInput executionInput, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to instrument aExecutionInput
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 usedparameters
- the parameters describing the field to be fetchedstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a non null instrumented ExecutionInput, the default is to return to the same object
-
instrumentDocumentAndVariables
@Deprecated @NotNull default @NotNull DocumentAndVariables instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables, InstrumentationExecutionParameters parameters)
Deprecated.This is called to instrument aDocument
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 usedparameters
- the parameters describing the execution- Returns:
- a non null instrumented DocumentAndVariables, the default is to return to the same objects
-
instrumentDocumentAndVariables
@NotNull default @NotNull DocumentAndVariables instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to instrument aDocument
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 usedparameters
- the parameters describing the executionstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a non null instrumented DocumentAndVariables, the default is to return to the same objects
-
instrumentSchema
@Deprecated @NotNull default @NotNull GraphQLSchema instrumentSchema(GraphQLSchema schema, InstrumentationExecutionParameters parameters)
Deprecated.This is called to instrument aGraphQLSchema
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 usedparameters
- the parameters describing the field to be fetched- Returns:
- a non null instrumented GraphQLSchema, the default is to return to the same object
-
instrumentSchema
@NotNull default @NotNull GraphQLSchema instrumentSchema(GraphQLSchema schema, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to instrument aGraphQLSchema
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 usedparameters
- the parameters describing the field to be fetchedstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a non null instrumented GraphQLSchema, the default is to return to the same object
-
instrumentExecutionContext
@Deprecated @NotNull default @NotNull ExecutionContext instrumentExecutionContext(ExecutionContext executionContext, InstrumentationExecutionParameters parameters)
Deprecated.This is called to instrument aExecutionContext
before it is used to execute a query, allowing you to adjust the base data used.- Parameters:
executionContext
- the execution context to be usedparameters
- the parameters describing the field to be fetched- Returns:
- a non null instrumented ExecutionContext, the default is to return to the same object
-
instrumentExecutionContext
@NotNull default @NotNull ExecutionContext instrumentExecutionContext(ExecutionContext executionContext, InstrumentationExecutionParameters parameters, InstrumentationState state)
This is called to instrument aExecutionContext
before it is used to execute a query, allowing you to adjust the base data used.- Parameters:
executionContext
- the execution context to be usedparameters
- the parameters describing the field to be fetchedstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a non null instrumented ExecutionContext, the default is to return to the same object
-
instrumentDataFetcher
@Deprecated @NotNull default @NotNull DataFetcher<?> instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters)
Deprecated.This is called to instrument aDataFetcher
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 usedparameters
- the parameters describing the field to be fetched- Returns:
- a non null instrumented DataFetcher, the default is to return to the same object
-
instrumentDataFetcher
@NotNull default @NotNull DataFetcher<?> instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters, InstrumentationState state)
This is called to instrument aDataFetcher
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 usedparameters
- the parameters describing the field to be fetchedstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a non null instrumented DataFetcher, the default is to return to the same object
-
instrumentExecutionResult
@Deprecated @NotNull default @NotNull java.util.concurrent.CompletableFuture<ExecutionResult> instrumentExecutionResult(ExecutionResult executionResult, InstrumentationExecutionParameters parameters)
Deprecated.This is called to allow instrumentation to instrument the execution result in some way- Parameters:
executionResult
-CompletableFuture
of the result to instrumentparameters
- the parameters to this step- Returns:
- a new execution result completable future
-
instrumentExecutionResult
@NotNull default @NotNull java.util.concurrent.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 instrumentparameters
- the parameters to this stepstate
- the state created during the call tocreateState(InstrumentationCreateStateParameters)
- Returns:
- a new execution result completable future
-
-