GraphOS 报告

将路由操作指标发送到 GraphOS

的GraphOS 路由器和 Apollo 路由器核心可以将操作使用指标报告给GraphOS，您可以在 GraphOS Studio 中可视化的。这些指标还启用了 GraphOS 强大的功能，如模式检查。

启用使用情况报告

您可以通过设置以下环境变量来在路由器中启用使用情况报告：

1
export APOLLO_KEY=<YOUR_GRAPH_API_KEY>
2
export APOLLO_GRAPH_REF=<YOUR_GRAPH_ID>@<VARIANT_NAME>

更多信息，请参阅向 GraphOS 发送操作指标。

上报字段级跟踪

在向您的 router 的响应中，您的子图可以包括字段级跟踪以指示子图解决字段所需的时间。通过在 GraphOS Studio 中分析此数据，您可以识别和优化较慢的字段：

您的子图库必须支持联邦跟踪（也称为FTV1跟踪）以提供这些数据。

要确认支持，请检查FEDERATED TRACING您库条目的该页面此页面。
查阅您库的文档了解如何启用联邦跟踪。
- 如果您使用 Apollo Server 与 @apollo/subgraph，联邦跟踪支持将自动启用。

子图跟踪采样

默认情况下，路由器请求子图跟踪数据，每个操作1%的采样概率。在大多数情况下，这提供了足够的样本量，同时最大限度地减少操作（跟踪可以影响延迟因为它们增加了子图响应的有效载荷大小）的延迟。

您可以通过在您的 YAML 配置文件中设置以下选项来自定义您的路由器的跟踪采样概率：

router.yaml

1
telemetry:
2
  apollo:
3
    # In this example, the trace sampler is configured  
4
    # with a 50% probability of sampling a request.
5
    # This value can't exceed the value of tracing.common.sampler.
6
    field_level_instrumentation_sampler: 0.5
7

8
  exporters:
9
    tracing:
10
      common:
11
        # FTV1 uses the same trace sampling as other tracing options,
12
        # so this value is also required.
13
        sampler: 0.5

ⓘ 注意

因为字段级仪表化取决于通用的OpenTelemetry 跟踪，telemetry.apollo.field_level_instrumentation_sampler的值不能超过telemetry.exporters.tracing.common.sampler的值。

禁用字段级跟踪

要完全禁用请求和报告子图跟踪数据，请将field_level_instrumentation_sampler设置为always_off：

router.yaml

1
telemetry:
2
  apollo:
3
    field_level_instrumentation_sampler: always_off

实验性的本地字段度量

Apollo Router可以发送字段级度量到GraphOS，而无需使用FTV1跟踪。这个特性是实验性的，目前在GraphOS Studio中不可见。要启用此功能，请在您的路由器配置中将experimental_local_field_metrics选项设置为true：

router.yaml

1
telemetry:
2
  apollo:
3
    experimental_local_field_metrics: true

高级配置

`send_headers`

提供此字段以配置包含在发送到GraphOS的跟踪数据中的请求数 headers名称和值。默认情况下，出于安全考虑，不向GraphOS发送任何headers信息。

router.yaml

1
telemetry:
2
  apollo:
3
    field_level_instrumentation_sampler: 0.01 # (default)
4
    send_headers:
5
      only: # Include only headers with these names
6
        - referer

支持值

值 / 类型	描述
`none` `字符串`	将`send_headers`设置为字符串值`none`以在报告的跟踪信息中包含没有任何headers信息。 send_headers: none 这是默认行为。
`all` `字符串`	将 `send_headers` 设置为字符串值 `all` 以包含所有的头信息在报告的跟踪信息中。 send_headers: all ⚠️ 小心使用！头信息可能包含敏感数据（如访问令牌），这些数据不应报告给 GraphOS。
`仅` `数组`	一个数组，包含路由器将报告给 GraphOS 的头名称。所有其他头信息不被报告。请参考上面的示例。
`除...` `数组`	一个数组，包含路由器不会报告给 GraphOS 的头名称。所有其他头被报告。请参考上面的 `only` 示例。

`send_variable_values`

提供此字段来配置哪些 GraphQL 变量的值包含在发送到 GraphOS 的跟踪数据中。默认情况下， 为了安全起见，不会将变量信息发送到 GraphOS。

router.yaml

1
telemetry:
2
  apollo:
3
    field_level_instrumentation_sampler: 0.01 # (default)
4
    send_variable_values:
5
      except: # Send all variables EXCEPT ones with these names
6
        - first

支持值

值 / 类型	描述
`none` `字符串`	将 `send_variable_values` 设置为字符串值 `none` 以包含无的变量信息在报告的跟踪信息中。 send_variable_values: none 这是默认行为。
`all` `字符串`	将 `send_variable_values` 设置为字符串值 `all` 以包含所有的变量信息在报告的跟踪信息中。 send_variable_values: all ⚠️ 小心使用！ GraphQL 变量可能包含敏感数据，不应报告给 GraphOS。
`仅` `数组`	一个数组，包含路由器将报告给 GraphOS 的变量名称。所有其他变量不被报告。请参考上面的 `except` 示例。
`除...` `数组`	一个数组，包含路由器不会报告给 GraphOS 的变量名称。所有其他变量被报告。

router.yaml

1
telemetry:
2
  apollo:
3
    # The percentage of requests will include HTTP request and response headers in traces sent to GraphOS Studio.
4
    # This is expensive and should be left at a low value.
5
    # This cannot be higher than tracing->common->sampler
6
    field_level_instrumentation_sampler: 0.01 # (default)
7

8
    # Include HTTP request and response headers in traces sent to GraphOS Studio
9
    send_headers: # other possible values are all, only (with an array), except (with an array), none (by default)
10
      except: # Send all headers except referer
11
        - referer
12

13
    # Include variable values in Apollo in traces sent to GraphOS Studio
14
    send_variable_values: # other possible values are all, only (with an array), except (with an array), none (by default)
15
      except: # Send all variable values except for variable named first
16
        - first
17
  exporters:
18
    tracing:
19
      common:
20
        sampler: 0.5 # The percentage of requests that will generate traces (a rate or `always_on` or `always_off`)

`errors`

您可以为是否将 GraphQL 错误信息报告给 GraphOS 以及是否对错误详情进行编辑进行配置。

默认情况下，您的路由器会报告错误信息，并且还会编辑那些错误的详情。

要防止您的路由器报告错误信息，可以将 send 选项设置为 false。
要包括所有错误详情在路由器发送到 GraphOS 的报告中，可以将 redact 选项设置为 false。

您的子图库必须支持联邦追踪（又名FTV1追踪），以便向GraphOS提供错误信息。如果您使用Apollo Server与@apollo/subgraph，联邦追踪支持将自动启用。

确认支持

检查FEDERATED TRACING条目，这位于支持的子图页面上。
如果您的库没有自动启用联邦追踪，请参考其文档以了解如何启用它。
请注意，联邦追踪也可以被采样（见上文），因此如果采样的级别较低，您可能无法获取所有操作的错误信息。

以下为示例

router.yaml

1
telemetry:
2
  apollo:
3
    errors:
4
      subgraph:
5
        all:
6
          # By default, subgraphs should report errors to GraphOS
7
          send: true # (default: true)
8
          redact: false # (default: true)
9
        subgraphs:
10
          account: # Override the default behavior for the "account" subgraph
11
            send: false

ⓘ 注意

如果您正在编写插件，您可以通过读取上下文中的apollo_operation_id的值来获取Studio追踪ID。

概览

客户端感知

GraphOS 报告

将路由操作指标发送到 GraphOS

启用使用情况报告

上报字段级跟踪

子图跟踪采样

禁用字段级跟踪

实验性的本地字段度量

高级配置

`send_headers`

`none`

`all`

`仅`

`除...`

`send_variable_values`

`none`

`all`

`仅`

`除...`

`errors`