Merge pull request #5960 from apollographql/release-3.6.0

Release 3.6.0

CHANGELOG.md

@@ -7,8 +7,9 @@ The version headers in this history reflect the versions of Apollo Server itself
 - [`@apollo/gateway`](https://github.com/apollographql/federation/blob/HEAD/gateway-js/CHANGELOG.md)
 - [`@apollo/federation`](https://github.com/apollographql/federation/blob/HEAD/federation-js/CHANGELOG.md)
 
-## vNEXT (minor!)
+## v3.6.0
 
+- `apollo-server-core`: Studio usage reporting now reports "referenced operations" for fields in addition to "field executions", which can be seen on the Studio Fields page. This new statistic provides visibility into uses of fields that are not executed. It is also more efficient to generate and (for Apollo Gateways) does not require subgraphs to support federated tracing. Additionally, the new `fieldLevelInstrumentation` option to `ApolloServerPluginUsageReporting` allows you to disable field-level tracing on a per-operation basis, and to report weights for operations to allow for estimates of the field execution count even when not all operations are instrumented. Note that the semantics of the `requestContext.metrics.captureTraces` field have changed. See the [Studio Fields page docs](https://www.apollographql.com/docs/studio/metrics/field-usage/) and the [`fieldLevelInstrumentation` docs](https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting/#fieldlevelinstrumentation) for more details. [Issue #5708](https://github.com/apollographql/apollo-server/issues/5708) [PR #5956](https://github.com/apollographql/apollo-server/pull/5956) [PR #5963](https://github.com/apollographql/apollo-server/pull/5963)
 - `apollo-server-core`: Usage reporting no longer sends a "client reference ID" to Apollo Studio (along with the client name and client version). This little-used feature has not been documented [since 2019](https://github.com/apollographql/apollo-server/pull/3180) and is currently entirely ignored by Apollo Studio. This is technically incompatible as the interface `ClientInfo` no longer has the field `clientReferenceId`; if you were one of the few users who explicitly set this field and you get a TypeScript compilation failure upon upgrading to v3.6.0, just stop using the field. [PR #5890](https://github.com/apollographql/apollo-server/pull/5890)
 - `apollo-server-core`: Remove dependency on `apollo-graphql` package (by inlining the code which generates usage reporting signatures). That package has not yet been published with a `graphql@16` peer dependency, so Apollo Server v3.5 did not fully support `graphql@16` without overriding peer dependencies. [Issue #5941](https://github.com/apollographql/apollo-server/issues/5941) [PR #5955](https://github.com/apollographql/apollo-server/pull/5955)
 

docs/source/api/plugin/usage-reporting.md

@@ -105,6 +105,40 @@ The only properties of the reported error you can modify are its `message` and i
 <tr>
 <td>
 
+###### `fieldLevelInstrumentation`
+
+`async Function` or `number`
+</td>
+<td>
+
+This option allows you to choose if Apollo Server should calculate detailed per-field statistics for a particular request. It is only called for executable operations: operations which parse and validate properly and which do not have an unknown operation name. It is not called if an [`includeRequest`](#includerequest) hook is provided and returns false.
+
+You can either pass an async function or a number. The function receives a `GraphQLRequestContext`. (The effect of passing a number is described later.) Your function can return a boolean or a number; returning false is equivalent to returning 0 and returning true is equivalent to returning 1.
+
+Returning false (or 0) means that Apollo Server will only pay attention to overall properties of the operation, like what GraphQL operation is executing and how long the entire operation takes to execute, and not anything about field-by-field execution.
+
+If you return false (or 0), this operation *will* still contribute to most features of Studio, such as schema checks, the Operations page, and the "referencing operations" statistic on the Fields page, etc.
+
+If you return false (or 0), this operation will *not* contribute to the "field executions" statistic on the Fields page or to the execution timing hints optionally displayed in Studio Explorer or in vscode-graphql. Additionally, this operation will not produce a trace that can be viewed on the Traces section of the Operations page.
+
+(For more information about the difference between the "referencing operations" and "field executions" statistics, see [the Studio Fields page documentation](https://apollographql.com/docs/studio/metrics/field-usage/).)
+
+Returning false (or 0) for some or all operations can improve your server's performance, as the overhead of calculating complete traces is not always negligible. This is especially the case if this server is an Apollo Gateway, as captured traces are transmitted from the subgraph to the Gateway in-band inside the actual GraphQL response.
+
+Returning a positive number means that Apollo Server will track each field execution and send Apollo Studio statistics on how many times each field was executed and what the per-field performance was. Apollo Server sends both a precise observed execution count and an estimated execution count. The former is calculated by counting each field execution as 1, and the latter is calculated by counting each field execution as the number returned from this hook, which can be thought of as a weight.
+
+Passing a number `x` (which should be between 0 and 1 inclusive) for `fieldLevelInstrumentation` is equivalent to passing the function `async () => Math.random() < x ? 1/x : 0`.  For example, if you pass 0.01, then 99% of the time this function will return 0, and 1% of the time this function will return 100. So 99% of the time Apollo Server will not track field executions, and 1% of the time Apollo Server will track field executions and send them to Apollo Studio both as an exact observed count and as an "estimated" count which is 100 times higher.  Generally, the weights you return should be roughly the reciprocal of the probability that the function returns non-zero; however, you're welcome to craft a more sophisticated function, such as one that uses a higher probability for rarer operations and a lower probability for more common operations.
+
+(Note that returning true here does *not* mean that the data derived from field-level instrumentation must be transmitted to Apollo Studio's servers in the form of a trace; it may still be aggregated locally to statistics. But either way this operation will contribute to the "field executions" statistic and timing hints.)
+
+The default `fieldLevelInstrumentation` is a function that always returns true.
+
+</td>
+</tr>
+
+<tr>
+<td>
+
 ###### `includeRequest`
 
 `async Function`
@@ -113,8 +147,12 @@ The only properties of the reported error you can modify are its `message` and i
 
 Specify this asynchronous function to configure which requests are included in usage reports sent to Apollo Studio. For example, you can omit requests that execute a particular operation or requests that include a particular HTTP header.
 
+ Note that returning false here means that the operation will be completely ignored by all Apollo Studio features. If you merely want to improve performance by skipping the field-level execution trace, set the [`fieldLevelInstrumentation`](#fieldlevelinstrumentation) option instead of this one.
+
 This function is called for each received request. It takes a [`GraphQLRequestContext`](https://github.com/apollographql/apollo-server/blob/main/packages/apollo-server-types/src/index.ts#L115-L150) object and must return a `Promise<Boolean>` that indicates whether to include the request. It's called either after the operation is successfully resolved (via [the `didResolveOperation` event](https://www.apollographql.com/docs/apollo-server/integrations/plugins/#didresolveoperation)), or when sending the final error response if the operation was not successfully resolved (via [the `willSendResponse` event](https://www.apollographql.com/docs/apollo-server/integrations/plugins/#willsendresponse)).
 
+If you don't want any usage reporting at all, don't use this option: instead, either avoid specifying an Apollo API key or explicitly [disable the plugin](#disabling-the-plugin).
+
 By default, all requests are included in usage reports.
 
 </td>

package.json

@@ -81,6 +81,7 @@
     "@types/koa-router": "7.4.4",
     "@types/lodash": "4.14.178",
     "@types/lodash.sortby": "4.7.6",
+    "@types/lodash.sumby": "4.6.6",
     "@types/lodash.xorby": "4.7.6",
     "@types/lru-cache": "5.1.1",
     "@types/memcached": "2.2.7",
@@ -112,10 +113,12 @@
     "jest": "27.4.5",
     "jest-config": "27.4.5",
     "jest-junit": "13.0.0",
+    "jest-mock-random": "1.1.1",
     "js-sha256": "0.9.0",
     "koa": "2.13.4",
     "koa-router": "10.1.1",
     "lerna": "4.0.0",
+    "lodash.sumby": "4.6.0",
     "log4js": "6.3.0",
     "memcached-mock": "0.1.0",
     "mock-req": "0.2.0",

packages/apollo-datasource-rest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apollo-datasource-rest",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "author": "Apollo <packages@apollographql.com>",
   "license": "MIT",
   "repository": {