Skip to content

Commit 4430712

Browse files
dondonzdondonz
committed
Adding edits
1 parent f973812 commit 4430712

1 file changed

Lines changed: 32 additions & 31 deletions

File tree

‎documentation/profiler.md‎

Lines changed: 32 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ description: How to avoid the dreaded N+1 calls for data and make your graphql s
66

77
# Profiling GraphQL requests
88

9-
We've introduced a new query profiling feature to help you understand the performance characteristics of your GraphQL executions. It provides detailed insights into data fetcher calls, data loader usage, and execution timing. This guide will show you how to use it and interpret the results.
9+
We've introduced a new profiling feature to help you understand the performance of your GraphQL executions. It provides detailed insights into DataFetcher calls, Dataloader usage, and execution timing. This guide will show you how to use it and interpret the results.
1010

11-
The Profiler is available in all versions after v25.0.beta-5. If you're not using a beta version, it will be included in the official v25.0 release.
11+
The Profiler is available in all versions after v25.0.beta-5. It will also be included in the forthcoming official v25.0 release.
1212

1313
## Enabling the Profiler
1414

@@ -22,7 +22,7 @@ import graphql.GraphQL;
2222
GraphQL graphql = GraphQL.newGraphQL(schema).build();
2323

2424
ExecutionInput executionInput = ExecutionInput.newExecutionInput()
25-
.query("{ hello }")
25+
.query("query Hello { world }")
2626
.profileExecution(true) // Enable profiling
2727
.build();
2828

@@ -48,40 +48,41 @@ ExecutionResult executionResult = graphql.execute(executionInput);
4848
ProfilerResult profilerResult = executionInput.getGraphQLContext().get(ProfilerResult.PROFILER_CONTEXT_KEY);
4949

5050
if (profilerResult != null) {
51-
// You now have access to the profiling data
5251
Map<String, Object> summary = profilerResult.shortSummaryMap();
53-
System.out.println(summary);
52+
System.out.println(summary); // or log
5453
}
5554
```
5655

56+
You could alternatively access and log the request's `ProfilerResult` from an `Instrumentation`.
57+
5758
## Understanding the Profiler Results
5859

59-
The `ProfilerResult` object contains a wealth of information. A great way to get a quick overview is by using the `shortSummaryMap()` method. It returns a map with key metrics about the execution. Let's break down what each key means.
60+
A great way to get a quick overview about `ProfilerResult` is by using the `shortSummaryMap()` method. It returns a map with key metrics about the execution, which you can use for logging. Let's break down what each key means.
6061

61-
### The Short Summary Map
62+
### The ProfilerResult Short Summary Map
6263

6364
Here's a detailed explanation of the fields you'll find in the map returned by `shortSummaryMap()`:
6465

65-
| Key | Type | Description |
66-
| ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
67-
| `executionId` | `String` | The unique ID for this GraphQL execution. |
68-
| `operationName` | `String` | The name of the operation, if one was provided in the query (e.g., `query MyQuery { ... }`). |
69-
| `operationType` | `String` | The type of operation, such as `QUERY`, `MUTATION`, or `SUBSCRIPTION`. |
70-
| `startTimeNs` | `long` | The system monotonic time in nanoseconds when the execution started. |
71-
| `endTimeNs` | `long` | The system monotonic time in nanoseconds when the execution finished. |
72-
| `totalRunTimeNs` | `long` | The total wall-clock time of the execution (`endTimeNs - startTimeNs`). This includes time spent waiting for asynchronous operations like database calls or external API requests within your data fetchers. |
66+
| Key | Type | Description |
67+
| ------------------------------------- | ----------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
68+
| `executionId` | `String` | The unique ID for this GraphQL execution. |
69+
| `operationName` | `String` | The name of the operation, if one was provided in the query (e.g., `query MyQuery { ... }`). |
70+
| `operationType` | `String` | The type of operation, such as `QUERY`, `MUTATION`, or `SUBSCRIPTION`. |
71+
| `startTimeNs` | `long` | The system time in nanoseconds when the execution started. |
72+
| `endTimeNs` | `long` | The system time in nanoseconds when the execution finished. |
73+
| `totalRunTimeNs` | `long` | The total wall-clock time of the execution (`endTimeNs - startTimeNs`). This includes time spent waiting for asynchronous operations like database calls or external API requests within your DataFetchers. |
7374
| `engineTotalRunningTimeNs` | `long` | The total time the GraphQL engine spent actively running on a thread. This is like the "CPU time" of the execution and excludes time spent waiting for `CompletableFuture`s to complete. Comparing this with `totalRunTimeNs` can give you a good idea of how much time is spent on I/O. |
74-
| `totalDataFetcherInvocations` | `int` | The total number of times any data fetcher was invoked. |
75-
| `totalCustomDataFetcherInvocations` | `int` | The number of invocations for data fetchers you've written yourself (i.e., not the built-in `PropertyDataFetcher`). This is often the most interesting data fetcher metric. |
76-
| `totalTrivialDataFetcherInvocations` | `int` | The number of invocations for the built-in `PropertyDataFetcher`, which simply retrieves a property from a POJO. |
77-
| `totalWrappedTrivialDataFetcherInvocations` | `int` | The number of invocations for data fetchers that wrap a `PropertyDataFetcher`. This usually happens when you use instrumentation to wrap data fetchers. |
78-
| `fieldsFetchedCount` | `int` | The number of unique fields fetched during the execution. |
79-
| `dataLoaderChainingEnabled` | `boolean` | `true` if the experimental data loader chaining feature was enabled for this execution. |
80-
| `dataLoaderLoadInvocations` | `Map` | A map where keys are data loader names and values are the number of times `load()` was called on them. Note that this counts all `load()` calls, including those that hit the data loader cache. |
81-
| `oldStrategyDispatchingAll` | `Set` | An advanced metric related to an older data loader dispatching strategy. It contains the execution levels where all data loaders were dispatched at once. |
82-
| `dispatchEvents` | `List<Map>` | A list of events, one for each time a data loader was dispatched. See below for details. |
83-
| `instrumentationClasses` | `List<String>` | A list of the fully qualified class names of the `Instrumentation` implementations used during this execution. |
84-
| `dataFetcherResultTypes` | `Map` | A summary of the types of values returned by your custom data fetchers. See below for details. |
75+
| `totalDataFetcherInvocations` | `int` | The total number of times any DataFetcher was invoked. |
76+
| `totalCustomDataFetcherInvocations` | `int` | The number of invocations for DataFetchers you've written yourself (i.e., not the built-in `PropertyDataFetcher`). |
77+
| `totalTrivialDataFetcherInvocations` | `int` | The number of invocations for the built-in `PropertyDataFetcher`. |
78+
| `totalWrappedTrivialDataFetcherInvocations` | `int` | The number of invocations for DataFetchers that wrap a `PropertyDataFetcher`. |
79+
| `fieldsFetchedCount` | `int` | The number of unique fields fetched during the execution. |
80+
| `dataLoaderChainingEnabled` | `boolean` | `true` if the experimental Dataloader chaining feature was enabled for this execution. |
81+
| `dataLoaderLoadInvocations` | `Map` | A map where keys are Dataloader names and values are the number of times `load()` was called on them. Note that this counts all `load()` calls, including those that hit the Dataloader cache. |
82+
| `oldStrategyDispatchingAll` | `Set` | If Chained DataLoaders are not used, the older dispatching strategy is used instead. This key lists the levels where DataLoaders were dispatched. |
83+
| `dispatchEvents` | `List<Map>` | A list of events, one for each time a Dataloader was dispatched. See below for details. |
84+
| `instrumentationClasses` | `List<String>` | A list of the class names of the `Instrumentation`s used during this execution. |
85+
| `dataFetcherResultTypes` | `Map` | A summary of the types of values returned by your custom DataFetchers. See below for details. |
8586

8687
#### `dispatchEvents`
8788

@@ -96,17 +97,17 @@ This is a list of maps, each detailing a `DataLoader` dispatch event.
9697

9798
#### `dataFetcherResultTypes`
9899

99-
This map gives you insight into the nature of your data fetchers' return values. This is especially useful for understanding the asynchronous behavior of your schema.
100+
This map gives you more information into the type of your DataFetchers' return values.
100101

101102
The keys are `COMPLETABLE_FUTURE_COMPLETED`, `COMPLETABLE_FUTURE_NOT_COMPLETED`, and `MATERIALIZED`.
102103
Each key maps to another map with two keys:
103-
* `count`: The number of unique fields with data fetchers that returned this result type.
104+
* `count`: The number of unique fields with DataFetchers that returned this result type.
104105
* `invocations`: The total number of invocations across all fields that returned this result type.
105106

106107
Here's what the result types mean:
107108

108109
| Result Type | Meaning |
109110
| ---------------------------------- | --------------------------------------------------------------------------------------------- |
110-
| `COMPLETABLE_FUTURE_COMPLETED` | The data fetcher returned a `CompletableFuture` that was already completed when it was returned. |
111-
| `COMPLETABLE_FUTURE_NOT_COMPLETED` | The data fetcher returned an incomplete `CompletableFuture`, indicating asynchronous work. |
112-
| `MATERIALIZED` | The data fetcher returned a simple value (i.e., not a `CompletableFuture`). |
111+
| `COMPLETABLE_FUTURE_COMPLETED` | The DataFetcher returned a `CompletableFuture` that was already completed when it was returned. |
112+
| `COMPLETABLE_FUTURE_NOT_COMPLETED` | The DataFetcher returned an incomplete `CompletableFuture`. |
113+
| `MATERIALIZED` | The DataFetcher returned a simple value (i.e., not a `CompletableFuture`). |

0 commit comments

Comments
 (0)