可观测性

Spring for GraphQL 直接集成了 Micrometer 可观测性支持。这为 GraphQL 请求和“非平凡的”数据获取操作提供了指标 (metrics) 和追踪 (traces)。由于 GraphQL 引擎运行在传输层之上，如果 Spring Framework 支持的话，您也应该可以 从传输层获得观测数据。

仅当应用程序中配置了 ObservationRegistry 时，才会发布观测数据 (observations)。您可以了解更多关于 在 Spring Boot 中配置可观测性基础设施 的信息。如果您想自定义 GraphQL 观测数据生成的元数据，您可以 直接在 instrumentation 上配置自定义约定 (convention)。如果您的应用程序使用 Spring Boot，推荐的方式是将自定义约定贡献为一个 bean。

服务器请求 instrumentation

GraphQL 服务器请求观测数据 (observations) 的名称为 "graphql.request"，适用于传统和响应式 (Reactive) 应用程序以及所有支持的传输方式。此 instrumentation 假定任何父级观测数据 (parent observation) 必须使用众所周知的 "micrometer.observation" 键在 GraphQL 上下文 (context) 中设置为当前观测数据。对于跨网络边界的追踪传播 (trace propagation)，必须由传输层的独立 instrumentation 负责。对于 HTTP，Spring Framework 提供了专门负责追踪传播的 instrumentation。

应用程序需要在其应用中配置 org.springframework.graphql.observation.GraphQlObservationInstrumentation instrumentation。默认情况下，它使用 org.springframework.graphql.observation.DefaultExecutionRequestObservationConvention，由 ExecutionRequestObservationContext 提供支持。

默认情况下，会创建以下 KeyValue：

表 1. 低基数键

名称

描述

graphql.operation (必需)

GraphQL 操作名称。

graphql.outcome (必需)

GraphQL 请求的结果。

graphql.operation KeyValue 将使用所提供查询的自定义名称，如果未提供，则使用 操作的标准名称 ("query"、"mutation" 或 "subscription")。graphql.outcome KeyValue 将是：

  • "SUCCESS" 如果已发送有效的 GraphQL 响应且不包含任何错误

  • "REQUEST_ERROR" 如果请求无法解析，或者响应包含错误（且没有错误类型为 org.springframework.graphql.execution.ErrorType.INTERNAL_ERROR）

  • "INTERNAL_ERROR" 如果无法生成有效的 GraphQL 响应，或者响应包含至少一个错误类型为 org.springframework.graphql.execution.ErrorType.INTERNAL_ERROR 的错误

表 2. 高基数键

名称

描述

graphql.execution.id (必需)

GraphQL 请求的 graphql.execution.ExecutionId。

Spring for GraphQL 还为服务器请求观测数据贡献事件 (Events)。Micrometer 观测事件 通常在追踪中作为 span 注解处理。此 instrumentation 将 GraphQL 响应中列出的错误记录为事件。

表 3. 观测事件

名称

上下文名称

GraphQL 错误类型，例如 InvalidSyntax

完整的 GraphQL 错误消息，例如 "Invalid syntax with offending token 'invalid'…​"

DataFetcher instrumentation

GraphQL DataFetcher 观测数据 (observations) 的名称为 "graphql.datafetcher"，仅针对被视为“非平凡的”数据获取操作创建（获取 Java 对象上的属性是平凡操作）。应用程序需要在其应用中配置 org.springframework.graphql.observation.GraphQlObservationInstrumentation instrumentation。默认情况下，它使用 org.springframework.graphql.observation.DefaultDataFetcherObservationConvention，由 DataFetcherObservationContext 提供支持。

默认情况下，会创建以下 KeyValue：

表 4. 低基数键

名称

描述

graphql.error.type (必需)

数据获取错误的类名

graphql.field.name (必需)

正在获取的字段名称。

graphql.outcome (必需)

GraphQL 数据获取操作的结果，“SUCCESS”或“ERROR”。
表 5. 高基数键

名称

描述

graphql.field.path (必需)

正在获取字段的路径（例如，"/bookById"）。