API参考：使用情况报告插件

从以下来源发送指标：Apollo服务器发送到 GraphOS 需要企业计划。如果您的组织尚未有企业计划，您可以通过注册一个免费的企业试用来测试此功能。

Apollo服务器's内置的使用情况报告插件收集有关您的客户端如何使用操作和字段的 GraphQL模式的。

此插件旨在在Apollo网关或单体服务器中使用；它不是为从子图中使用而设计的。在一个运行 Apollo联盟的 supergraph 中，Apollo网关或 GraphOS路由器将将使用情况报告发送到Apollo云。子图不需要也将使用情况报告发送到Apollo云；相反，它们通过内联跟踪将信息发送到路由器，而路由器则将所有子图的执行信息结合起来并发送汇总报告到云。

默认安装

📣 新功能：Apollo服务器4：默认情况下不包含错误详细信息。有关更多详细信息，请参阅错误处理。

Apollo服务器在您提供graph API密钥和graph ref到Apollo服务器以及您的服务器不是联邦子图时，自动安装并启用此插件（使用默认设置）。您通常通过设置 APOLLO_KEY 和 APOLLO_GRAPH_REF（或 APOLLO_GRAPH_ID 和 APOLLO_GRAPH_VARIANT）环境变量。无需其他操作。

如果您没有提供API密钥和图引用，或者如果您的服务器是联邦子图，则此插件不会自动安装。

如果提供了API密钥但没有提供图引用，将记录一条警告。您可以通过禁用插件来隐藏警告。

如果提供了API密钥和图引用，但您的服务器是联邦子图，则将记录一条警告。您可以通过禁用插件来隐藏警告。

自定义安装

如果您想配置使用情况报告插件，导入它并将其传递到您的 ApolloServer构造函数的 plugins数组中：

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginUsageReporting } from '@apollo/server/plugin/usageReporting';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [
8
    ApolloServerPluginUsageReporting({
9
      fieldLevelInstrumentation: 0.5,
10
    }),
11
  ],
12
});

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginUsageReporting } from '@apollo/server/plugin/usageReporting';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [
8
    ApolloServerPluginUsageReporting({
9
      fieldLevelInstrumentation: 0.5,
10
    }),
11
  ],
12
});

虽然您可以在联邦子图服务器上安装使用情况报告插件，但这不推荐使用，并将记录一条警告。

以下列出了支持的配置选项。

选项

名称 / 类型	描述
配置发送到Apollo Studio的数据
`sendVariableValues` `对象`	请提供此对象以配置要包含在发送到 Apollo Studio 的跟踪数据中的 GraphQL 变量值。有效选项的描述请见有效的 `sendVariableValues` 对象签名。默认值是 `{ none: true }`, 表示不将任何变量值发送到 Studio。这是一个安全措施，防止敏感数据可能发送到 Apollo 服务器。
`sendHeaders` `对象`	提供此对象以配置哪些请求头名称和值要包含在发送到 Apollo Studio 的跟踪数据中。有效选项的描述请见有效的 `sendHeaders` 对象签名。默认值是 `{ none: true }`, 表示不将任何头名称或值发送到 Studio。这是一个安全措施，防止敏感数据可能发送到 Apollo 服务器。
`sendErrors` `对象`	提供此对象以在 Apollo Server 报告这些错误到 Apollo Studio 之前修改 GraphQL 操作错误。有效选项的描述请见有效的 `sendErrors` 对象签名。默认值是 `{ masked: true }`, 表示错误消息被隐藏，并且扩展被省略，在 Apollo Server 发送到 Apollo Studio 的跟踪中。这是一个安全措施，防止敏感数据可能发送到 Apollo 服务器。注意：如果此 `ApolloServer` 实例作为 Apollo Federation 架构中的网关，则此选项不会修改来自子图子图的错误。要修改这些错误，请配置子图的 `inline trace` 插件中的的 `includeErrors` 选项，您需要将其安装在子图的 `ApolloServer` 实例中。
`fieldLevelInstrumentation` `async Function` 或 `数字`	此选项允许您配置 Apollo Server 是否为每个操作计算详细的每个字段统计数据。它仅用于没有遇到错误（例如在解析、验证或解析操作名称时）的执行操作。如果您提供了一个返回 `false` 的 `includeRequest` 钩子，则它不会被使用。您可以提供数字或异步函数。如果您提供一个数字，该数字必须在 `0` 到 `1` 之间（包括0和1）。这个数字指定了Apollo Server为每个传入的操作计算的字段统计的概率。例如，如果您传递 `0.01` ，则Apollo Server为大约1%的操作计算统计信息。当Apollo Server将这些统计信息报告给Apollo Studio时，它还提供每个字段的实际执行次数的“估计乘数”（例如，概率为 `0.01` 时，估计乘数为 `100` ）。提供数字 `x` 相当于调用此函数： `async () => Math.random() < x ? 1/x : 0` 如果您传递一个函数，该函数将为每个操作调用一次，并且它将传递相应的 `GraphQLRequestContext` 对象。该函数可以返回一个布尔值或数字。返回 `false` 等价于返回 `0` ，返回 `true` 等价于返回 `1` 。如果函数返回 `false` (或 `0` ) 该操作不贡献于Studio中字段页面上的“字段执行”统计信息，或贡献于在探索器或VS Code中显示的执行时间提示。该操作不产生可以查看于Studio中操作页面“跟踪”部分的跟踪。该操作仍然贡献于Studio的多数功能，例如模式检查、操作页面以及字段页面上的“引用操作”统计信息。 (有关“引用操作”和“字段执行”统计信息之间差异的更多信息，请参阅 Studio字段页面文档。) 对于某些或所有操作返回 `false` (或 `0` )可以提高服务器性能，因为计算完整的跟踪可能会带来显著的开销。这在配置了联邦图时格外正确，因为跟踪被传输到实际GraphQL响应内的网关中。如果函数返回一个正数 Apollo Server会为相关的操作计算字段统计信息，并将其发送到Apollo Studio。 Apollo Server 向 Studio 同时发送每个观察到的运行次数和一个估计的总运行次数。观察到的运行次数是每个字段在相关操作中解决的次数。估计的总运行次数是观察到的运行次数，乘以该函数返回的数字。你可以将这个返回的数字视为一个“估计乘数”。为了确定函数应返回的“估计乘数”，取该函数为相关操作返回非零数值的频率的倒数。例如，如果该函数在某个特定操作中每十次执行中返回一次非零数值，那么它返回的数字应该是 `10`。你的函数可以为不同的操作使用不同的逻辑，例如，比通常的操作更频繁地报告罕见操作。请注意，在此处返回 `true` 并不意味着来自字段级别的数据必须以追踪的形式发送到 Apollo Studio 的服务器。数据仍然可以本地汇总为统计数据。无论哪种方式，这个操作都有助于 Studio 中的“字段执行”统计，包括时间提示。默认值是一个始终返回 `true` 的函数。
`includeRequest` `异步函数`	指定此异步函数以配置要发送到 Apollo Studio 的使用报告中包含哪些请求。例如，您可以省略执行特定操作或包含特定 HTTP 标头的请求。请注意，在此处返回 `false` 表示该操作完全被所有 Apollo Studio 功能忽略。如果你想通过跳过字段级别的执行跟踪来提高性能，请改为设置 `fieldLevelInstrumentation` 选项，而不是此选项。此函数为每个接收到的请求调用一次。它接收一个 `GraphQLRequestContext` 对象，并必须返回一个 `Promise<Boolean>`，指示是否包含请求。它在 "didResolveOperation" 事件之后或者在传送最终错误响应时调用（如果 "willSendResponse" 事件）。如果您完全不希望有任何使用情况的报告，请不要使用此选项：相反，您可以选择避免指定 Apollo API 密钥或显式禁用插件. 默认情况下，所有请求都会包含在使用报告中。
`generateClientInfo` `函数`	指定此函数以向 Apollo Studio 提供每个已处理请求的客户详细信息。Apollo Studio 使用此信息来按客户分段指标。此函数接收一个包含所有请求信息的`GraphQLRequestContext`对象。它应返回一个对象，包含`clientName`和`clientVersion`字段，以标识相关客户。默认情况下，插件会尝试从传入请求的 HTTP 报头中获取这些值（特别是，`apollographql-client-name`和`apollographql-client-version`）。
`overrideReportedSchema` `字符串`	如果您使用的是`overrideReportedSchema`选项与模式报告插件（`ApolloServerPluginSchemaReporting`），您应该为该选项提供相同的值。这样可以确保在此插件的使用报告中与请求关联的模式 ID 与其他插件报告的模式 ID 匹配。
`sendUnexecutableOperationDocuments` `布尔型`	关于服务器无法执行的操作的统计数据不会在每个文档下分别报告给 Apollo Studio，而是分组为“解析失败”、“验证失败”或“未知操作名称”。默认情况下，使用情况报告插件不会在报告中包括完整的操作文档，因为从无效操作中剥离潜在的私有信息（如字符串常量）很具挑战性。如果您想让使用情况报告插件发送完整的操作文档和操作名称，以便您可以在 Apollo Studio 的跟踪视图中查看它们，请将此设置为 true。
配置通信协议
`sendReportsImmediately` `布尔型`	如果`true`，插件在每个请求后都会将使用报告发送到 Apollo Studio，而不是发送批量报告。默认情况下，此选项设置为`false`。此选项对于类似于 Amazon Lambda 的无状态环境很有用，在这些环境中，在处理少量请求后进程会终止。请注意，“立即”并不意味着与完成响应同步，而是指“很快”，例如在`setImmediate`调用后。
`fetcher` `typeof fetch`	指定用于发送使用报告时的Fetch API函数实现。
`reportIntervalMs` `数字`	Apollo Server 向 Studio 发送批量跟踪报告的时间间隔（以毫秒为单位）。无论此值如何，只要挂起的批量大小超过 `maxUncompressedReportSize` 的值（默认 4MB），Apollo Server 都会发送跟踪报告。
`maxUncompressedReportSize` `数字`	Apollo Server 在挂起的批量跟踪报告的大小超过此值（以字节为单位）时发送跟踪报告，无论其标准报告间隔如何。请注意，此为粗略的限制，包括序列化跟踪和签名的尺寸。它忽略了报告标题和一些其他顶级字节的尺寸。默认值为 4MB（`4194304`）。
`maxAttempts` `数字`	Apollo Server 尝试报告每个跟踪报告的最大次数，在尝试之间执行指数退避。默认值为 `5`。
`minimumRetryDelayMs` `数字`	Apollo Server 重试失败的跟踪报告前应执行的最低退避时间（以毫秒为单位）。默认值为 `100`。
`requestTimeoutMs` `数字`	将报告发送到 Apollo 的每个单独尝试的超时时间。（这适用于每个 HTTP POST，而不是所有可能的重试。）默认值为 `30000`（30秒）。
`logger` `Logger`	如果您提供此对象，插件将发送所有与 Apollo Studio 通信相关的日志消息，而不是发送到默认日志记录器。该对象必须实现 `Logger` 接口的所有方法。
`reportErrorFunction` `函数`	如果您提供此函数，插件在遇到报告使用数据时的错误时将调用它。错误详情将传递给该函数。默认情况下，插件将其记录到指定的 `logger`。与 `logger` 不同，此函数接收实际的 `Error` 对象，而不仅仅是错误消息。
内部和非推荐选项
`endpointUrl` `字符串`	插件发送报告的基本 URL（不包含路径）。此选项仅需要设置用于测试和 Apollo 内部使用。
`debugPrintReports` `布尔型`	如果设置，则在发送时将所有报告作为 JSON 打印。（注意，出于技术原因，嵌入在报告中的跟踪在添加到报告中时将被单独打印。）
`calculateSignature` `函数`	指定此函数以创建查询的签名。此选项不建议使用，因为 Apollo 服务器对签名与您执行的操作之间的关系有一些假设。

有效的 `sendVariableValues` 对象签名

对象	描述
`{ none: true }`	如果提供此对象，则不会向 Apollo Studio 发送任何 GraphQL 变量值。这是默认行为。
`{ all: true }`	如果提供此对象，将发送给 Apollo Studio 的 GraphQL 变量值将是全部。
`{ onlyNames: ["apple", "orange"]}`	如果提供具有此结构的对象，则只有名称出现在数组中的 GraphQL 变量的值才会发送给 Apollo Studio。要过滤包含输入类型的变量的单个字段，请使用下面的 `transform` 函数。区分大小写。
`{ exceptNames: ["apple", "orange"]}`	如果提供具有此结构的对象，则发送给 Apollo Studio 的 GraphQL 变量值将除了出现在数组中的变量值之外的所有值。要过滤包含输入类型的变量的单个字段，请使用下面的 `transform` 函数。区分大小写。
`{ transform: ({ variables, operationString)} => { ... } }`	`transform` 的值是一个函数，该函数接收一个操作的所有 GraphQL变量的值和操作字符串。该函数返回一个包含应发送到 Apollo Studio 的操作变量的值的新变量映射。此映射不需要包含操作的所有变量，但不得添加变量到映射中。您不应修改 `variables` 本身或其中包含的任何值。出于安全原因，如果在 `transform` 函数中发生错误，所有变量值都将替换为 `[PREDICATE_FUNCTION_ERROR]`。

有效的 `sendHeaders` 对象签名

对象	描述
`{ none: true }`	如果提供此对象，则不会向 Apollo Studio 发送任何请求头名称或值。这是默认行为。
`{ all: true }`	如果提供此对象，则将向 Apollo Studio 发送所有 GraphQL 头名称和值，但以下受保护的头除外。
`{ onlyNames: ["apple", "orange"]}`	如果提供具有此结构的对象，则仅将名称和值发送给 Apollo Studio 的请求头名称出现在数组中，不区分大小写。
`{ exceptNames: ["apple", "orange"]}`	如果提供具有此结构的对象，则发送给 Apollo Studio 的 GraphQL 头值将是除了出现在数组中的头值之外的所有值。不区分大小写。

注意： 无论配置如何，Apollo Server 永远不会 向 Apollo Studio 发送以下头部的值：

授权
cookie
set-cookie

有效的 `sendErrors` 对象签名

对象	描述
`{ masked: true }`	如果提供此对象，错误消息将被掩盖，并且跟踪中的 extensions 被省略。这是默认行为。
`{ unmodified: true }`	如果提供此对象，则将在发送到 Apollo Studio 的跟踪中包含所有错误消息和 extensions。
`{ transform: (err: GraphQLError) => { GraphQLError \| null }}`	`transform` 的值是一个函数，该函数接收每个错误（`GraphQLError`），并必须返回一个 GraphQLError 对象（或 `null` 以防止 Apollo Server 报告特定的错误）。您可以修改已报告错误的唯一属性是它的 `消息` 和它的 `扩展`。有关更多详细信息，请参阅错误遮罩和错误日志。

禁用插件

如果您 不想安装使用情况报告插件，并且您 正在为 Apollo Server 提供其他目的的 API 密钥，您可以通过安装 ApolloServerPluginUsageReportingDisabled 插件来禁用使用情况报告，如下所示：

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginUsageReportingDisabled } from '@apollo/server/plugin/disabled';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [ApolloServerPluginUsageReportingDisabled()],
8
});

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginUsageReportingDisabled } from '@apollo/server/plugin/disabled';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [ApolloServerPluginUsageReportingDisabled()],
8
});

如果您提供了 API 密钥但没有提供 graph ref 或如果您提供了 API 密钥和 graph ref 但您的服务器是一个联合子图，这也会禁用警告日志。

API参考：使用情况报告插件

默认安装

自定义安装

选项

`sendVariableValues`

`sendHeaders`

`sendErrors`

`fieldLevelInstrumentation`

`includeRequest`

`generateClientInfo`

`overrideReportedSchema`

`sendUnexecutableOperationDocuments`

`sendReportsImmediately`

`fetcher`

`reportIntervalMs`

`maxUncompressedReportSize`

`maxAttempts`

`minimumRetryDelayMs`

`requestTimeoutMs`

`logger`

`reportErrorFunction`

`endpointUrl`

`debugPrintReports`

`calculateSignature`

有效的 `sendVariableValues` 对象签名

有效的 `sendHeaders` 对象签名

有效的 `sendErrors` 对象签名

`{ masked: true }`

`{ unmodified: true }`

`{ transform: (err: GraphQLError) => { GraphQLError | null }}`

禁用插件