このバージョンはまだ開発中であり、まだ安定しているとは考えられていません。最新のスナップショットバージョンについては、Spring AI 1.0.3 を使用してください。

可観測性

Spring AI は、Spring エコシステムの可観測性機能に基づいて構築され、AI 関連の操作に関する分析情報を提供します。

可観測性を有効にするには、spring-boot-actuator モジュールが必要です。プロジェクトの Maven pom.xml ビルドファイルに Spring Boot Actuator 依存関係を追加してください。

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

または、Gradle build.gradle ビルドファイルに保存します。

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

Spring AI provides metrics and tracing capabilities for its core components: ChatClient (including Advisor), ChatModel、EmbeddingModel、ImageModel、VectorStore.

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

1.0.0-RC1 重大な変更

次の構成プロパティは、目的をより適切に反映するために名前が変更されました。

  • spring.ai.chat.client.observations.include-prompt → spring.ai.chat.client.observations.log-prompt

  • spring.ai.chat.observations.include-prompt → spring.ai.chat.observations.log-prompt

  • spring.ai.chat.observations.include-completion → spring.ai.chat.observations.log-completion

  • spring.ai.image.observations.include-prompt → spring.ai.image.observations.log-prompt

  • spring.ai.vectorstore.observations.include-query-response → spring.ai.vectorstore.observations.log-query-response

チャットクライアント

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: 高カーディナリティキー
名前 説明

gen_ai.prompt

チャットクライアント経由で送信されるプロンプトの内容。オプション。

spring.ai.chat.client.advisor.params (非推奨)

アドバイザーパラメーターのマップ。会話 ID が spring.ai.chat.client.conversation.id に含まれるようになりました。

spring.ai.chat.client.advisors

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

spring.ai.chat.client.conversation.id

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

spring.ai.chat.client.system.params (非推奨)

チャットクライアントのシステムパラメーター。オプション。gen_ai.prompt に置き換えられました。

spring.ai.chat.client.system.text (非推奨)

チャットクライアントのシステムテキスト。オプション。gen_ai.prompt に置き換えられました。

spring.ai.chat.client.tool.function.names (非推奨)

有効なツール機能名。spring.ai.chat.client.tool.names に置き換えられました。

spring.ai.chat.client.tool.function.callbacks (非推奨)

構成されたチャットクライアント関数のコールバックのリスト。spring.ai.chat.client.tool.names に置き換えられました。

spring.ai.chat.client.tool.names

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

spring.ai.chat.client.user.params (非推奨)

チャットクライアントのユーザーパラメーター。オプション。gen_ai.prompt に置き換えられました。

spring.ai.chat.client.user.text (非推奨)

チャットクライアントのユーザーテキスト。オプション。gen_ai.prompt に置き換えられました。

Prompt and Completion Data

The ChatClient prompt and completion data is typically big and possibly containing sensitive information. For those reasons, it is not exported by default.

Spring AI supports logging the prompt and completion data to help with debugging and troubleshooting.

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

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

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

false

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

Whether to log the chat client completion content.

false

If you enable logging of the chat client prompt and completion data, there’s a risk of exposing sensitive or private information. Please, be careful!

入力データ (非推奨)

spring.ai.chat.client.observations.include-input プロパティは非推奨となり、spring.ai.chat.client.observations.log-prompt に置き換えられました。プロンプトコンテンツを参照してください。

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

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

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

spring.ai.chat.client.observations.include-input

入力コンテンツを観測に含めるかどうか。

false

入力内容を観測に含めることを有効にすると、機密情報や個人情報が公開されるリスクがあります。ご注意ください。

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

spring.ai.advisor 観測は、アドバイザーの実行時に記録されます。アドバイザー内で費やされた時間（内部アドバイザーで費やされた時間を含む）を測定し、関連するトレース情報を伝播します。

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

gen_ai.operation.name

常に framework です。

gen_ai.system

常に spring_ai です。

spring.ai.advisor.type (非推奨)

アドバイザーがリクエスト処理においてロジックを適用する場所は、BEFORE、AFTER、AROUND のいずれかです。すべてのアドバイザーは常に同じ型であるため、この区別は適用されません。

spring.ai.kind

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

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

spring.ai.advisor.name

アドバイザーの名前。

spring.ai.advisor.order

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

チャットモデル

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

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.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.input_tokens

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

gen_ai.usage.output_tokens

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

gen_ai.usage.total_tokens

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

gen_ai.prompt

モデルに送信される完全なプロンプト。オプション。

gen_ai.completion

モデルから受信した完全なレスポンス。オプション。

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

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

gen_ai.system

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

spring.ai.kind

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

spring.ai.tool.definition.name

ツールの名前。

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

名前

説明

spring.ai.tool.definition.description

ツールの説明。

spring.ai.tool.definition.schema

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

spring.ai.tool.call.arguments

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

spring.ai.tool.call.result

ツールを呼び出すために使用されるパラメーターのスキーマ。(有効になっている場合のみ)

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

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

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

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

spring.ai.tools.observations.include-content

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

false

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

EmbeddingModel

可観測性機能は現在、Azure、OpenAI、Mistral AI、Ollama、OpenAI の AI モデルプロバイダーの EmbeddingModel 実装でのみサポートされています。追加の 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 の観測は、イメージモデルメソッドの呼び出し時に記録されます。メソッドの完了に費やされた時間を測定し、関連するトレース情報を伝播します。

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

gen_ai.operation.name

実行される操作の名前。

gen_ai.system

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

gen_ai.request.model

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

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

gen_ai.request.image.response_format

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

gen_ai.request.image.size

生成するイメージのサイズ。

gen_ai.request.image.style

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

gen_ai.response.id

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

gen_ai.response.model

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

gen_ai.usage.input_tokens

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

gen_ai.usage.output_tokens

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

gen_ai.usage.total_tokens

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

gen_ai.prompt

モデルに送信される完全なプロンプト。オプション。

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

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

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

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、hana、simple のいずれか。

spring.ai.kind

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

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

db.collection.name

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

db.namespace

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

db.record.id

存在する場合はレコード識別子。

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 → 前回のスクレイプ以降の最高水位 (レジストリの動作に従う)