このバージョンはまだ開発中であり、まだ安定しているとは見なされていません。最新の安定バージョンについては、Spring AI 1.1.7 を使用してください！

可観測性

Spring AI は、Spring エコシステムの可観測性機能に基づいて構築され、AI 関連の運用に関するインサイトを提供します。コアコンポーネントである ChatClient （Advisor を含む）、ChatModel、EmbeddingModel、ImageModel、VectorStore のメトリクスとトレース機能を提供します。

アプリケーションでメトリクスとトレースのサポートを有効にするには、Spring Boot メトリクスおよび Spring Boot トレースのドキュメントを参照してください。

カーディナリティの低いキーはメトリクスとトレースの両方に追加され、カーディナリティの高いキーはトレースのみに追加されます。

チャットクライアント

spring.ai.chat.client 観測は、ChatClient call() または stream() 操作が呼び出されたときに記録されます。呼び出しの実行に費やされた時間を測定し、関連するトレース情報を伝播します。

表 1: 低カーディナリティキー
名前 説明

gen_ai.operation.name

常に framework です。

gen_ai.system

常に spring_ai です。

spring.ai.chat.client.stream

チャットモデルのレスポンスはストリームですか - true or false

spring.ai.kind

Spring AI のフレームワーク API の種類: chat_client。

表 2: 高カーディナリティキー

名前

説明

spring.ai.chat.client.advisors

構成されたチャットクライアントアドバイザーのリスト。

spring.ai.chat.client.conversation.id

チャットメモリを使用する場合の会話の識別子。

spring.ai.chat.client.tool.names

チャットクライアントに渡されるツールの名前。

プロンプトと完了データ

ChatClient のプロンプトと補完データは通常サイズが大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、デバッグとトラブルシューティングに役立つプロンプトと完了データのログ記録をサポートしています。

プロパティ 説明 デフォルト

spring.ai.chat.client.observations.log-prompt

チャットクライアントのプロンプトの内容をログに記録するかどうか。

false

spring.ai.chat.client.observations.log-completion

チャットクライアントの完了内容をログに記録するかどうか。

false

チャットクライアントのプロンプトと完了データのログ記録を有効にすると、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

チャットクライアントアドバイザー

spring.ai.advisor 観測値は、アドバイザーが実行された際に記録されます。これらの観測値は、アドバイザーの実行時間（内部アドバイザーの実行時間を含む）を測定し、関連する追跡情報を伝達します。

表 3: 低カーディナリティキー
名前 説明

gen_ai.operation.name

常に framework です。

gen_ai.system

常に spring_ai です。

spring.ai.advisor.name

アドバイザーの名前。

spring.ai.kind

Spring AI のフレームワーク API の種類: advisor。

表 4: 高カーディナリティキー
名前 説明

spring.ai.advisor.order

アドバイザーチェーンのアドバイザーオーダー。

チャットモデル

OpenAI と Anthropic のチャットモデルはどちらも HTTP レイヤーの観測値（チャットモデルレイヤー＋ HTTP レイヤー）を出力しますが、ストリーミング呼び出しに特有の制限が 1 つあります。HTTP レイヤーの観測値には HTTP メソッド、URI、ステータスコードが含まれ、traceparent をネットワーク経由で下流サービス（AI ゲートウェイ、プロキシ、OpenAI 互換の推論サーバー）に伝播します。

For synchronous calls, the okhttp.requests span is correctly nested under the gen_ai.client.operation span. For streaming calls, the HTTP span is recorded but is not parented under the chat-model span — the SDK’s async streaming path hops onto ForkJoinPool.commonPool() before invoking Spring AI’s HTTP client, dropping the calling thread’s observation context at that boundary.

See the OpenAI chat docs and Anthropic chat docs for details.

gen_ai.client.operation 観測は、ChatModel call または stream メソッドを呼び出すときに記録されます。メソッドの完了に費やされた時間を測定し、関連するトレース情報を伝播します。

gen_ai.client.token.usage メトリクスは、単一のモデル呼び出しで使用される入力トークンと出力トークンの数を測定します。
表 5: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

クライアントインストルメンテーションによって識別されるモデルプロバイダー。

gen_ai.request.model

リクエストが行われているモデルの名前。

gen_ai.response.model

レスポンスを生成したモデルの名前。

表 6: 高カーディナリティキー
名前 説明

gen_ai.request.frequency_penalty

モデルリクエストの頻度ペナルティ設定。

gen_ai.request.max_tokens

モデルがリクエストに対して生成するトークンの最大数。

gen_ai.request.presence_penalty

モデルリクエストのプレゼンスペナルティ設定。

gen_ai.request.stop_sequences

モデルがそれ以上のトークンの生成を停止するために使用するシーケンスのリスト。

gen_ai.request.stream

リクエストがストリーミングモードで行われたかどうか。true の場合のみ存在します。

gen_ai.request.temperature

モデルリクエストの温度設定。

gen_ai.request.top_k

モデルリクエストの top_k サンプリング設定。

gen_ai.request.top_p

モデルリクエストの top_p サンプリング設定。

gen_ai.response.finish_reasons

受信した各世代に対応する、モデルがトークンの生成を停止した理由。

gen_ai.response.id

AI レスポンスの一意の識別子。

gen_ai.usage.cache_creation.input_tokens

プロバイダが管理するキャッシュに書き込まれた入力トークンの数。

gen_ai.usage.cache_read.input_tokens

プロバイダが管理するキャッシュから提供される入力トークンの数。

gen_ai.usage.input_tokens

モデル入力 (プロンプト) で使用されるトークンの数。

gen_ai.usage.output_tokens

モデル出力（完了）で使用されるトークンの数。

gen_ai.usage.total_tokens

モデル交換で使用されるトークンの合計数。

spring.ai.model.request.tool.names

リクエストでモデルに提供されるツール定義のリスト。

ユーザートークンを測定する場合、前の表には観測トレースに存在する値がリストされています。ChatModel によって提供されるメトリクス名 gen_ai.client.token.usage を使用します。

チャットプロンプトと完了データ

チャットプロンプトと完了データは通常サイズが大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、チャットプロンプトと完了データのログ記録をサポートしており、トラブルシューティングに役立ちます。トレースが利用可能な場合、ログにはトレース情報が含まれるため、相関関係の精度が向上します。

プロパティ 説明 デフォルト

spring.ai.chat.observations.log-prompt

プロンプトの内容をログに記録します。true または false

false

spring.ai.chat.observations.log-completion

完了内容をログに記録します。true または false

false

spring.ai.chat.observations.include-error-logging

観測にエラーログを含めます。true または false

false

チャットプロンプトと完了データのログ記録を有効にすると、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

ツール呼び出し

spring.ai.tool の観測値は、チャットモデルのインタラクションにおいてツール呼び出しを実行する際に記録されます。これらの観測値は、ツール呼び出しの完了に要した時間を測定し、関連するトレース情報を伝達します。

表 7: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行中の操作の名前。常に execute_tool です。

gen_ai.system

操作を担当するプロバイダー。常に spring_ai です。

spring.ai.kind

Spring AI が実行する操作の種類。常に tool_call です。

spring.ai.tool.definition.name

ツールの名前。

spring.ai.tool.type

ツールの種類。デフォルトでは function です。

表 8: 高カーディナリティキー

名前

説明

spring.ai.tool.definition.description

ツールの説明。

spring.ai.tool.definition.schema

ツールを呼び出すために使用されるパラメーターのスキーマ。

spring.ai.tool.call.id

チャットモデルによって識別される、ツール呼び出しの ID。

spring.ai.tool.call.arguments

ツール呼び出しへの入力引数。(有効になっている場合のみ)

spring.ai.tool.call.result

ツール呼び出しの実行結果。(有効になっている場合のみ)

ツール呼び出し引数と結果データ

入力引数とツール呼び出しの結果は、潜在的に機密情報である可能性があるため、デフォルトではエクスポートされません。

Spring AI は、ツール呼び出し引数と結果データをスパン属性としてエクスポートすることをサポートしています。

プロパティ 説明 デフォルト

spring.ai.tools.observations.include-content

観測にツール呼び出しコンテンツを含めます。true または false

false

ツール呼び出しの引数と結果を観測に含めるように設定した場合、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

EmbeddingModel

オブザーバビリティ機能は現在、以下の AI モデルプロバイダーによる EmbeddingModel 実装でのみサポートされています: Mistral AI、Ollama、OpenAI。今後のリリースでは、その他の AI モデルプロバイダーもサポートされる予定です。

gen_ai.client.operation の観測は、埋め込みモデルメソッド呼び出しに記録されます。メソッドの完了に費やされた時間を測定し、関連するトレース情報を伝播します。

gen_ai.client.token.usage メトリクスは、単一のモデル呼び出しで使用される入力トークンと出力トークンの数を測定します。
表 9: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

クライアントインストルメンテーションによって識別されるモデルプロバイダー。

gen_ai.request.model

リクエストが行われているモデルの名前。

gen_ai.response.model

レスポンスを生成したモデルの名前。

表 10: 高カーディナリティキー
名前 説明

gen_ai.request.embedding.dimensions

結果として得られる出力埋め込みの次元数。

gen_ai.usage.input_tokens

モデル入力で使用されるトークンの数。

gen_ai.usage.total_tokens

モデル交換で使用されるトークンの合計数。

ユーザートークンを測定する場合、前の表には観測トレースに存在する値がリストされています。EmbeddingModel によって提供されるメトリクス名 gen_ai.client.token.usage を使用します。

イメージモデル

可観測性機能は現在、次の AI モデルプロバイダーの ImageModel 実装でのみサポートされています: OpenAI。追加の AI モデルプロバイダーは、将来のリリースでサポートされる予定です。

gen_ai.client.operation の観測は、イメージモデルメソッドの呼び出し時に記録されます。メソッドの完了に費やされた時間を測定し、関連するトレース情報を伝播します。

表 11: 低カーディナリティキー
名前 説明

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

クライアントインストルメンテーションによって識別されるモデルプロバイダー。

gen_ai.request.model

リクエストが行われているモデルの名前。

表 12: 高カーディナリティキー
名前 説明

gen_ai.request.image.response_format

生成されたイメージが返される形式。

gen_ai.request.image.size

生成するイメージのサイズ（例: 1024x1024）。

gen_ai.request.image.style

生成するイメージのスタイル。

イメージプロンプトデータ

イメージプロンプトデータは通常サイズが大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、トラブルシューティングに役立つイメージプロンプトデータのログ記録をサポートしています。トレースが利用可能な場合、ログにはトレース情報が含まれるため、相関関係の精度が向上します。

プロパティ 説明 デフォルト

spring.ai.image.observations.log-prompt

イメージプロンプトの内容をログに記録します。true または false

false

イメージプロンプトデータのログ記録を有効にすると、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

ベクトルストア

Spring AI のすべてのベクトルストア実装は、Micrometer を通じてメトリクスと分散トレースデータを提供するようにインストルメント化されています。

db.vector.client.operation の観測は、ベクトルストアとやり取りするときに記録されます。query、add、remove 操作に費やされた時間を測定し、関連するトレース情報を伝播します。

表 13: 低カーディナリティキー
名前 説明

db.operation.name

実行される操作またはコマンドの名前。add、delete、または query のいずれかです。

db.system

クライアントインストルメンテーションによって識別されるデータベース管理システム (DBMS) 製品。pg_vector、azure、cassandra、chroma、elasticsearch、milvus、neo4j、opensearch、qdrant、redis、typesense、weaviate、pinecone、oracle、mongodb、gemfire、simple のいずれか。

spring.ai.kind

Spring AI のフレームワーク API の種類: vector_store。

表 14: 高カーディナリティキー
名前 説明

db.collection.name

データベース内のコレクション (テーブル、コンテナー) の名前。

db.namespace

サーバーアドレスとポート内で完全修飾されたデータベースの名前。

db.search.similarity_metric

類似性検索で使用されるメトリクス。

db.vector.dimension_count

ベクトルの次元。

db.vector.field_name

ベクトルの名前フィールド (フィールド名など)。

db.vector.query.content

実行中の検索クエリの内容。

db.vector.query.filter

検索クエリで使用されるメタデータフィルター。

db.vector.query.response.documents

類似検索クエリから返されたドキュメント。オプション。

db.vector.query.similarity_threshold

すべての検索スコアを受け入れる類似度しきい値。しきい値が 0.0 の場合、すべての類似度が受け入れられるか、類似度しきい値フィルタリングが無効になります。しきい値が 1.0 の場合、完全一致が必要です。

db.vector.query.top_k

クエリによって返される上位 k 個の最も類似したベクトル。

レスポンスデータ

ベクトル検索レスポンスデータは通常大きく、機密情報が含まれている可能性があります。そのため、デフォルトではエクスポートされません。

Spring AI は、トラブルシューティングに役立つベクトル検索レスポンスデータのログ記録をサポートしています。トレースが利用可能な場合、ログにはトレース情報が含まれるため、相関関係の精度が向上します。

プロパティ 説明 デフォルト

spring.ai.vectorstore.observations.log-query-response

ベクトルストアクエリレスポンスの内容をログに記録します。true または false

false

ベクトル検索レスポンスデータのログ記録を有効にすると、機密情報や個人情報が漏洩するリスクがあります。ご注意ください。

その他のメトリクスリファレンス

このセクションでは、Prometheus に表示される、Spring AI コンポーネントによって生成されたメトリクスについて説明します。

メトリクスの命名規則

Spring AI は Micrometer を使用します。基本メトリクス名はドット（例: gen_ai.client.operation）を使用し、Prometheus はアンダースコアと標準のサフィックスを使用してエクスポートします。

  • タイマー→ <base>_seconds_count、<base>_seconds_sum、<base>_seconds_max、および（サポートされている場合） <base>_active_count

  • カウンター→ <base>_total (単調)

以下は、基本メトリクス名が Prometheus 時系列にどのように拡張されるかを示しています。

基本メトリクス名 エクスポートされた時系列

gen_ai.client.operation

gen_ai_client_operation_seconds_count
gen_ai_client_operation_seconds_sum
gen_ai_client_operation_seconds_max
gen_ai_client_operation_active_count

db.vector.client.operation

db_vector_client_operation_seconds_count
db_vector_client_operation_seconds_sum
db_vector_client_operation_seconds_max
db_vector_client_operation_active_count

参照

チャットクライアントのメトリクス

メトリクス名 タイプ 単位 説明

gen_ai_chat_client_operation_seconds_sum

タイマー

秒

ChatClient 運用に費やされた合計時間 (呼び出し / ストリーム)

gen_ai_chat_client_operation_seconds_count

カウンター

カウント

完了した ChatClient 操作の数

gen_ai_chat_client_operation_seconds_max

ゲージ

秒

ChatClient 運用の最大観測期間

gen_ai_chat_client_operation_active_count

ゲージ

カウント

現在飛行中の ChatClient 運用の数

アクティブ vs 完了 : active_count は進行中の呼び出しを表示します。_seconds シリーズは完了した呼び出しのみを反映します。

チャットモデルメトリクス (モデルプロバイダーの実行)

メトリクス名 タイプ 単位 説明

gen_ai_client_operation_seconds_sum

タイマー

秒

チャットモデル操作の実行時間合計

gen_ai_client_operation_seconds_count

カウンター

カウント

完了したチャットモデル操作の数

gen_ai_client_operation_seconds_max

ゲージ

秒

チャットモデル操作の最大観測期間

gen_ai_client_operation_active_count

ゲージ

カウント

現在実行中のチャットモデル操作の数

トークンの使用

メトリクス名 タイプ 単位 説明

gen_ai_client_token_usage_total

カウンター

トークン

消費されたトークンの合計（トークンの種類別）

ラベル

ラベル 意味

gen_ai_token_type=input

モデルに送信されるプロンプトトークン

gen_ai_token_type=output

モデルによって返される完了トークン

gen_ai_token_type=total

入力 + 出力

ベクトルストアメトリクス

メトリクス名 タイプ 単位 説明

db_vector_client_operation_seconds_sum

タイマー

秒

ベクトルストア操作に費やされた合計時間 (追加 / 削除 / クエリ)

db_vector_client_operation_seconds_count

カウンター

カウント

完了したベクトルストア操作の数

db_vector_client_operation_seconds_max

ゲージ

秒

ベクトルストア操作の最大観測期間

db_vector_client_operation_active_count

ゲージ

カウント

現在実行中のベクトルストア操作の数

ラベル

ラベル 意味

db_operation_name

操作型 (add、delete、query)

db_system

ベクトル DB/ プロバイダー (redis、chroma、pgvector, …)

spring_ai_kind

vector_store

アクティブと完了の違いを理解する

  • アクティブ (*_active_count) — 進行中の操作 (同時実行性 / 負荷) の瞬間的なゲージ。

  • 完了 (*_seconds_sum|count|max) — 終了した操作の統計:

  • _seconds_sum / _seconds_count → 平均レイテンシ

  • _seconds_max → 前回のスクレイプ以降の最高水位 (レジストリの動作に従う)