graphql.execution.instrumentation

Interface Instrumentation

All Known Implementing Classes:

ChainedInstrumentation, DataLoaderDispatcherInstrumentation, FieldValidationInstrumentation, MaxQueryComplexityInstrumentation, MaxQueryDepthInstrumentation, SimpleInstrumentation, TracingInstrumentation

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 and Description
DeferredFieldInstrumentationContext	beginDeferredField(InstrumentationDeferredFieldParameters parameters) This is called just before a deferred field is resolved into a value.
InstrumentationContext<ExecutionResult>	beginExecuteOperation(InstrumentationExecuteOperationParameters parameters) This is called just before the execution of the query operation is started.
InstrumentationContext<ExecutionResult>	beginExecution(InstrumentationExecutionParameters parameters) This is called right at the start of query execution and its the first step in the instrumentation chain.
ExecutionStrategyInstrumentationContext	beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters) This is called each time an ExecutionStrategy is invoked, which may be multiple times per query as the engine recursively descends down over the query.
InstrumentationContext<ExecutionResult>	beginField(InstrumentationFieldParameters parameters) This is called just before a field is resolved into a value.
default InstrumentationContext<ExecutionResult>	beginFieldComplete(InstrumentationFieldCompleteParameters parameters) This is called just before the complete field is started.
InstrumentationContext<java.lang.Object>	beginFieldFetch(InstrumentationFieldFetchParameters parameters) This is called just before a field DataFetcher is invoked.
default InstrumentationContext<ExecutionResult>	beginFieldListComplete(InstrumentationFieldCompleteParameters parameters) This is called just before the complete field list is started.
InstrumentationContext<Document>	beginParse(InstrumentationExecutionParameters parameters) This is called just before a query is parsed.
InstrumentationContext<java.util.List<ValidationError>>	beginValidation(InstrumentationValidationParameters parameters) This is called just before the parsed query document is validated.
default InstrumentationState	createState() 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
default InstrumentationState	createState(InstrumentationCreateStateParameters parameters) 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
default DataFetcher<?>	instrumentDataFetcher(DataFetcher<?> dataFetcher, InstrumentationFieldFetchParameters parameters) 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 DocumentAndVariables	instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables, InstrumentationExecutionParameters parameters) 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 ExecutionContext	instrumentExecutionContext(ExecutionContext executionContext, InstrumentationExecutionParameters parameters) This is called to instrument a ExecutionContext before it is used to execute a query, allowing you to adjust the base data used.
default ExecutionInput	instrumentExecutionInput(ExecutionInput executionInput, InstrumentationExecutionParameters parameters) 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 java.util.concurrent.CompletableFuture<ExecutionResult>	instrumentExecutionResult(ExecutionResult executionResult, InstrumentationExecutionParameters parameters) This is called to allow instrumentation to instrument the execution result in some way
default GraphQLSchema	instrumentSchema(GraphQLSchema schema, InstrumentationExecutionParameters parameters) 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 Detail

createState

default InstrumentationState createState()

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

default InstrumentationState createState(InstrumentationCreateStateParameters parameters)

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

beginExecution

InstrumentationContext<ExecutionResult> beginExecution(InstrumentationExecutionParameters parameters)

This is called right at the start of query execution and its 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

beginParse

InstrumentationContext<Document> beginParse(InstrumentationExecutionParameters parameters)

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

beginValidation

InstrumentationContext<java.util.List<ValidationError>> beginValidation(InstrumentationValidationParameters parameters)

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

beginExecuteOperation

InstrumentationContext<ExecutionResult> beginExecuteOperation(InstrumentationExecuteOperationParameters parameters)

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

beginExecutionStrategy

ExecutionStrategyInstrumentationContext beginExecutionStrategy(InstrumentationExecutionStrategyParameters parameters)

This is called each time an ExecutionStrategy 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 InstrumentationContext object that will be called back when the step ends

beginDeferredField

DeferredFieldInstrumentationContext beginDeferredField(InstrumentationDeferredFieldParameters parameters)

This is called just before a deferred 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

InstrumentationContext<ExecutionResult> beginField(InstrumentationFieldParameters parameters)

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

beginFieldFetch

InstrumentationContext<java.lang.Object> beginFieldFetch(InstrumentationFieldFetchParameters parameters)

This is called just before a field DataFetcher is invoked.

Parameters:

parameters - the parameters to this step

Returns:

a non null InstrumentationContext object that will be called back when the step ends

beginFieldComplete

default InstrumentationContext<ExecutionResult> beginFieldComplete(InstrumentationFieldCompleteParameters parameters)

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

beginFieldListComplete

default InstrumentationContext<ExecutionResult> beginFieldListComplete(InstrumentationFieldCompleteParameters parameters)

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

instrumentExecutionInput

default ExecutionInput instrumentExecutionInput(ExecutionInput executionInput,
                                                InstrumentationExecutionParameters parameters)

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

Returns:

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

instrumentDocumentAndVariables

default DocumentAndVariables instrumentDocumentAndVariables(DocumentAndVariables documentAndVariables,
                                                            InstrumentationExecutionParameters parameters)

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

Returns:

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

instrumentSchema

default GraphQLSchema instrumentSchema(GraphQLSchema schema,
                                       InstrumentationExecutionParameters parameters)

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

Returns:

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

instrumentExecutionContext

default ExecutionContext instrumentExecutionContext(ExecutionContext executionContext,
                                                    InstrumentationExecutionParameters parameters)

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

Returns:

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

instrumentDataFetcher

default DataFetcher<?> instrumentDataFetcher(DataFetcher<?> dataFetcher,
                                             InstrumentationFieldFetchParameters parameters)

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

Returns:

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

instrumentExecutionResult

default java.util.concurrent.CompletableFuture<ExecutionResult> instrumentExecutionResult(ExecutionResult executionResult,
                                                                                          InstrumentationExecutionParameters parameters)

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

Returns:

a new execution result completable future