向 GraphOS 发送指标

了解如何向 GraphOS 报告操作和字段使用指标

GraphOS Studio提供了请求率、延迟等指标的可视化，以帮助您分析您的supergraph的性能。Studio 还允许您分析客户端如何在您的 GraphQL 请求中单独使用字段。要分析 Studio 中的操作指标和字段使用情况，您首先需要将它们报告到 GraphOS。

从Apollo Server或从monograph报告指标需要 Enterprise 或 legacy Team 计划。
将自托管路由器连接到GraphOS需要 Enterprise 计划。

报告操作指标

您如何向GraphOS报告操作指标取决于您是否使用GraphOS Router 或 Apollo Server，或者您是否使用第三方服务器。

从 GraphOS Router 或 Apollo Server

GraphOS Router和Apollo Server使用相同的机制启用操作指标向 GraphOS 的报告：

从GraphOS Studio获取graph API key。
⚠️ 注意
API 密钥是保密凭证。切勿将它们在组织外部共享或提交到版本控制。删除并替换您认为已泄露的 API 密钥。
访问 studio.apollographql.com 然后点击 graph 以获取相应的API密钥。
如果出现 发布你的Schema 对话框，复制之后出现的受保护值。APOLLO_KEY= 例子中的代码块（以 service: 开始），然后一切就绪。
否则，进行下一步。
打开你的 graph's 的设置页面并选择API键标签。点击 创建新键。给你的密钥命名，比如 Production。这有助于你跟踪每个API键的使用情况。
ⓘ 注意
如果您看不到API键标签，说明您对 graph 的权限不足。只有具有 组织管理员 或 Graph管理员 角色才能管理 graph API键。了解更多关于成员角色。
复制密钥的值。出于安全考虑，创建后在Studio中无法查看API键的值。
ⓘ 注意
您所使用的 graph API键必须至少具有 贡献者 角色以报告非受保护的 variant 的指标，并且具有 组织管理员 或 Graph管理员 角色以报告受保护变体的指标。
获取您要报告指标的 graph 和 variant 的 graph ref。您可以在Studio中该variant的README页面的顶部找到您的variant的 graph ref（格式为 graph-id@variant-name，例如 my-graph@staging）。
使用获取到的值，在启动您的 router/server 之前设置以下环境变量：
export APOLLO_KEY=<YOUR_GRAPH_API_KEY>
export APOLLO_GRAPH_REF=<YOUR_GRAPH_REF>

ⓘ 注意

参考您的生产环境文档，了解如何设置其环境变量。

现在，当您的路由器或服务器启动时，它将自动开始向 GraphOS 报告操作指标。

GraphOS 路由器增强报告

如果您使用 GraphOS 路由器报告操作指标，您可以为更全面的洞察和操作检查配置增强操作签名归一化和扩展引用报告。

从第三方服务器（高级）

您可以在您的GraphQL 服务器中设置一个报告代理，以将指标推送到 GraphOS。代理负责：

将操作细节转换为正确的报告格式
实现默认签名函数以识别每个执行的操作
向 GraphOS 报告端点发射跟踪和指标批次
可选地定义插件以启用高级报告功能

Apollo Server在其使用报告插件中定义了执行这些任务的代理。

ⓘ 注意

如果您有兴趣与Apollo合作创建您的专用集成GraphQL服务器，请联系我们至[email protected].

报告格式

GraphOS报告端点接受以协议缓冲区格式编码的跟踪和指标批次。每个跟踪对应一个GraphQL操作的执行，包括该操作中每个解析的字段的时间分解和错误信息。这个协议缓冲区的架构被定义为Report信息在protobuf架构中。

该protobuf架构文件

描述了如何创建一个报告，其中tracesPerQuery对象仅包含trace数组中的详细执行跟踪。GraphOS现在允许您的服务器将使用情况描述为详细执行跟踪和预聚合指标的混合（在Apollo Server 2.24版本中发布），这导致报告更加高效。本文件不描述如何生成这些指标。也不描述如何在Insights页面上的客户端 & 操作表格中报告特定操作的请求数量。

ⓘ 注意

我们强烈建议开发者在使用此模块构建自己的报告代理之前，联系Apollo支持至[email protected]讨论他们的使用情况。

作为起点，我们建议实现一个扩展，将GraphQL执行创建一个包含单个跟踪的报告，如Trace消息中定义的protobuf架构。然后，您可以将多个跟踪打包成一个报告。我们建议每20秒发送一批，并将每批的大小限制在合理的范围内（约4MB）。

许多服务器运行时已经支持将跟踪信息作为GraphQL扩展发送。这类扩展适用于Node，Ruby，Scala，Java，Elixir，以及.NET。如果您正在为这些语言之一添加指标报告功能，阅读这些跟踪仪器是一种好的开始。对于其他语言，我们建议查阅Apollo Server用法报告插件。

操作签名

为了使GraphOS Studio能够正确地对GraphQL查询进行分组，您的报告代理应该定义一个生成每个不同操作签名的函数。这可能具有挑战性，因为两个结构上不同的操作可能是功能上等效的。例如，以下所有查询都请求相同的信息：

1
query AuthorForPost($foo: String!) {
2
  post(id: $foo) {
3
    author
4
  }
5
}
6

7
query AuthorForPost($bar: String!) {
8
  post(id: $bar) {
9
    author
10
  }
11
}
12

13
query AuthorForPost {
14
  post(id: "my-post-id") {
15
    author
16
  }
17
}
18

19
query AuthorForPost {
20
  post(id: "my-post-id") {
21
    writer: author
22
  }
23
}

在跟踪度量指标时，决定如何对这些查询进行分组非常重要。TypeScript参考实现对每个查询在生成签名之前执行以下操作，以更好地分组功能上等效的操作：

删除未使用的片段和/或操作
隐藏字符串字面量
忽略别名
以确定性方式排序树
忽略空白符的差异。

我们建议在不同服务器运行时保持一致性，使用相同的默认签名方法。

向报告端点发送指标

当您的GraphQL服务器准备好一批跟踪数据时，它应将它们发送到以下URL的 Studio报告端点：

1
https://usage-reporting.api.apollographql.com/api/ingress/traces

每个批次应作为HTTP POST请求发送。请求正文可以是以下之一

一个报告消息的二进制序列化
一个报告消息的gzip二进制序列化

要认证Studio，每个请求必须包含以下之一

一个X-Api-Key头，包含您的graph有效API密钥
一个authtokencookie，包含您的graph有效API密钥

仅支持以前缀service:开头的图级API密钥。

请求可以可选地包含一个值为application/protobuf的Content-Type头部，但这不是必需的。

⚠️ 注意

报告端点拒绝超过50分钟的报告。如果你看到类似拒绝来自服务{你的服务}的报告，时间戳有偏移的错误，请确保你的跟踪信息是最新的，而且你时间戳的计算是准确的。

有关参考实现，请参阅sendReport()函数，该函数位于TypeScript参考代理。

调整报告行为

当你遇到与报告端点通信时的5xx响应或网络错误时，我们建议实现带有回退的重试。另外，实现关闭钩子以确保服务器在稳定关闭前推送所有挂起的报告。

实现其他报告功能

参考TypeScript实现包括了你可能想在实现中包含的几个功能。所有这些功能都在用法报告插件中实现，并在插件的API参考中进行了文档说明。

例如，你可以限制发送给GraphOS的信息，尤其是为了避免发送个人信息。由于个人信息通常出现在变量和头部中，TypeScript代理提供了sendVariablesValues和sendHeaders的选项。

报告字段使用指标

你的GraphQL router 或 server 可以报告以下字段使用指标之一或两个：

请求：观察到一个特定字段请求的操作的次数
执行：对特定字段解析器的执行次数

你如何将这些指标报告给GraphOS取决于你是否使用GraphOS Router或Apollo Server。

从GraphOS Router

如果您有一个

云

超级图或者

自托管超级图

，您只需配置您的

路由器

以将操作度量发送到GraphOS，并且字段使用情况将自动报告。

子图

不应直接向GraphOS发送任何度量。相反，它们可以在对

路由器

的响应中包含

跟踪数据。然后，路由器将包括该数据在其对GraphOS的报告中。

ⓘ 注意

子图使用联邦跟踪实现将字段跟踪和错误数据发送到路由器。这意味着您的子图必须支持联邦跟踪，并且在您开始看到超级图的GraphOS中的错误详细信息之前，它已为您环境的启用。

从Apollo Server

Apollo Server可自动报告字段使用度量，只要您遵循以下先决条件：

您必须首先配置服务器以将操作度量发送到GraphOS。
报告请求
- 您的GraphQL服务器必须运行Apollo Server 3.6或更高版本。
- 如果您有一个联邦图，您的网关必须运行Apollo Server 3.6或更高版本，但您的子图没有要求。
报告执行
- 您的GraphQL服务器可以运行任何最新的Apollo Server 2.x或3.x版本。
- 如果您有一个联邦图，您的子图必须支持联邦跟踪。有关兼容库，请参阅FEDERATED TRACING中的库的条目，请参见此表。

ⓘ 注意

如果您的一些子图支持联邦跟踪，而其他不支持，则只有兼容子图的执行报告到Apollo。

禁用执行度量

在Apollo Server 3.6及更高版本中，您可以通过提供fieldLevelInstrumentation选项到ApolloServerPluginUsageReporting来关闭某些或所有操作的字段级instrumentation。

关闭特定请求的字段级instrumentation有以下影响：

请求不会对 Studio 中的“执行”统计信息做出贡献。
请求不会对字段级别的执行时间提示做出贡献，这些提示可以在
请求不会在 Studio 中“洞察”页面的“跟踪”部分产生可查看的跟踪。

这些请求仍然会对 Studio 的大多数功能做出贡献，例如

要禁用所有请求的字段级别仪表，请将 () => false 作为 fieldLevelInstrumentation 选项传递：

1
new ApolloServer({
2
  plugins: [
3
    ApolloServerPluginUsageReporting({
4
      fieldLevelInstrumentation: () => false
5
    })
6
  ]
7
  // ...
8
});

如果您这样做，执行度量将不会出现在洞察页面上。

分数采样

您可以通过传递介于 0 和 1 之间的数字作为 fieldLevelInstrumentation 选项来为一固定比例的所有请求启用字段级别仪表：

1
new ApolloServer({
2
  plugins: [
3
    ApolloServerPluginUsageReporting({
4
      fieldLevelInstrumentation: 0.01
5
    })
6
  ]
7
  // ...
8
});

如果您这样做，Apollo Server 将根据给定的概率随机选择对每个请求启用字段级别仪表。

⚠️ 注意

请确保传递一个数字（例如 0.01），而不是一个总是返回相同数字的函数（例如 () => 0.01），它具有不同的效果。

在这种情况下， whenever 字段级别仪表对特定请求启用时，Apollo Server 根据给定的概率将其报告给 Studio，并带有相应的权重。洞察页面上的“执行”统计信息（以及执行时间提示）会根据此权重进行缩放。

例如，如果您传递 0.01，则您的服务器将约为 1% 的请求启用字段级别执行，并且每个观察到的执行都被计为洞察页面上的 100 个执行。（实际的观察到的执行计数可在表格的提示中查看。）

自定义采样

您可以通过传递函数作为 fieldLevelInstrumentation 的值，在操作级别上决定是否启用字段级别仪表（以及权重应为多少）：

例如，您可能希望更频繁地启用字段级仪表化来处理罕见操作，而较少地用于常见操作。有关详细信息，请参阅使用报告插件文档。

性能考虑因素

计算执行指标可能会影响大型查询或高流量图的性能。对于联邦图来说尤其如此，因为子图包括每个操作的全部跟踪数据在响应中。

概览

操作签名