可観測性

Micrometer による可観測性のサポート (英語) は Spring for GraphQL に直接組み込まれています。これにより、GraphQL リクエストのメトリクスとトレースの両方と、「重要な」データフェッチ操作が可能になります。GraphQL エンジンはトランスポート層の上で動作するため、Spring Framework でサポートされている場合は、トランスポートからの観測も期待する必要があります。

アプリケーションで ObservationRegistry が構成されている場合にのみ、観察結果が公開されます。Spring Boot でオブザーバビリティインフラストラクチャの構成について詳しく知ることができます。GraphQL 観測で生成されたメタデータをカスタマイズする場合は、インストルメンテーションでカスタム規則を直接構成できます。アプリケーションが 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` (必須)	GraphQL オペレーション名。
`graphql.outcome` (必須)	GraphQL リクエストの結果。

graphql.operation KeyValue は、提供されたクエリのカスタム名を使用するか、何もない場合は操作の標準名 (英語) ("query"、"mutation" または "subscription") を使用します。graphql.outcome KeyValue は、有効な GraphQL レスポンスが送信された場合は "SUCCESS" になり、リクエストを解析できなかった場合は "REQUEST_ERROR" になり、有効な GraphQL レスポンスを生成できなかった場合は "INTERNAL_ERROR" になります。

表 2: カーディナリティの高いキー
名前	説明
`graphql.execution.id` (必須)	GraphQL リクエストの `graphql.execution.ExecutionId`。

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")。