可观测性

DeepSeek V3 中英对照 Observability

通过 Micrometer 实现可观测性支持已直接集成到 Spring for GraphQL 中。这为 GraphQL 请求和“非平凡”的数据获取操作提供了指标和追踪功能。由于 GraphQL 引擎运行在传输层之上，如果 Spring Framework 支持，您还应该期望从传输层获得观测数据。

只有当应用程序中配置了 ObservationRegistry 时，观测数据才会被发布。你可以了解更多关于在 Spring Boot 中配置可观测性基础设施的信息。如果你想自定义 GraphQL 观测数据生成的元数据，可以直接在 instrumentation 上配置自定义约定。如果你的应用程序使用 Spring Boot，将自定义约定作为 bean 提供是首选方式。

服务器请求检测

GraphQL 服务器请求观测记录以 "graphql.request" 为名称创建，适用于传统和响应式应用，并覆盖所有支持的传输协议。此检测机制假定任何父级观测记录必须通过已知的 "micrometer.observation" 键设置为 GraphQL 上下文中的当前观测。对于跨网络边界的追踪传播，必须在传输层进行独立的检测处理。以 HTTP 为例，Spring Framework 提供了专门的检测机制来处理追踪传播。

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

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

表 1. 低基数键

名称	描述
graphql.operation.type (必填)	GraphQL 操作类型。
graphql.outcome (必填)	GraphQL 请求的结果。

graphql.operation.type 键值将使用操作的标准名称（"query"、"mutation" 或 "subscription"），如果请求文档无法解析，则使用 "operation"。

graphql.outcome 键值对将是：

• "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。
graphql.operation.name (必填)	GraphQL 操作名称。

graphql.operation.name 键值将类似于 graphql.operation.name，将使用客户端提供的操作名称。

Spring for GraphQL 同样为服务器请求观测提供了事件支持。Micrometer 观测事件通常在追踪中作为跨度注解处理。该工具会将 GraphQL 响应中列出的错误记录为事件。

表 3. 观测事件

名称	上下文名称
GraphQL 错误类型，例如 InvalidSyntax	完整的 GraphQL 错误消息，例如 "Invalid syntax with offending token 'invalid'…​"

DataFetcher 检测

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

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

表 4. 低基数键

名称	描述
graphql.error.type (必需)	数据获取错误的类名
graphql.field.name (必需)	正在获取的字段名称。
graphql.outcome (必需)	GraphQL 数据获取操作的结果，为 "SUCCESS" 或 "ERROR"。

表 5. 高基数键

名称	描述
graphql.field.path (必填)	要获取的字段的路径（例如，"/bookById"）。

DataLoader 仪表化

GraphQL DataLoader 观测记录以名称 "graphql.dataloader" 创建，用于观测对 @BatchMapping 控制器方法的调用以及手动注册的 DataLoader 实例。应用程序需要在应用中配置 org.springframework.graphql.observation.GraphQlObservationInstrumentation 检测工具。默认情况下，它使用 org.springframework.graphql.observation.DefaultDataLoaderObservationConvention，并由 DataLoaderObservationContext 提供支持。

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

表 6. 低基数键

名称	描述
graphql.error.type (必需)	数据获取错误的类名
graphql.loader.name (必需)	正在使用的 DataLoader 的名称。
graphql.outcome (必需)	GraphQL 数据获取操作的结果，为 "SUCCESS" 或 "ERROR"。

表 7. 高基数键

名称	描述
graphql.loader.size (必填)	已加载元素列表的大小。