可観測性

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

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

チャットクライアント

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.advisor.params`	アドバイザーパラメーターのマップ。
`spring.ai.chat.client.advisors`	構成されたチャットクライアントアドバイザーのリスト。
`spring.ai.chat.client.system.params`	チャットクライアントのシステムパラメーター。オプション。
`spring.ai.chat.client.system.text`	チャットクライアントのシステムテキスト。オプション。
`spring.ai.chat.client.tool.function.names`	有効なツール機能名。
`spring.ai.chat.client.tool.function.callbacks`	構成されたチャットクライアント関数コールバックのリスト。
`spring.ai.chat.client.user.params`	チャットクライアントのユーザーパラメーター。オプション。
`spring.ai.chat.client.user.text`	Chat client user text. Optional.

Input Data

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

Spring AI supports exporting input data as span attributes across all tracing backends.

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

プロパティ	説明	デフォルト
`spring.ai.chat.client.observations.include-input`	Whether to include the input content in the observations.	`false`

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

Whether to include the input content in the observations.

false

If you enable the inclusion of the input content in the observations, there’s a risk of exposing sensitive or private information. Please, be careful!

Chat Client Advisors

The spring.ai.advisor observations are recorded when a call or stream around advisors is performed. They measure the time spent in the advisor (including the time spend on the inner advisors) and propagate the related tracing information.

表 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`	Name of the advisor.
`spring.ai.advisor.order`	Advisor order in the advisor chain.

Chat Model

Observability features are currently supported only for ChatModel implementations from the following AI model providers: Anthropic, Azure OpenAI, Mistral AI, Ollama, OpenAI, Vertex AI, MiniMax, Moonshot, QianFan, Zhiu AI. Additional AI model providers will be supported in a future release.

The gen_ai.client.operation observations are recorded when calling the ChatModel call or stream methods. They measure the time spent on method completion and propagate the related tracing information.

The gen_ai.client.token.usage metrics measures number of input and output tokens used by a single model call.

表 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`	The total number of tokens used in the model exchange.
`gen_ai.prompt`	The full prompt sent to the model. Optional.
`gen_ai.completion`	The full response received from the model. Optional.

For measuring user tokens, the previous table lists the values present in an observation trace. Use the metric name gen_ai.client.token.usage that is provided by the ChatModel.

表 7: イベント
名前	説明
`gen_ai.content.prompt`	Event including the content of the chat prompt. Optional.
`gen_ai.content.completion`	Event including the content of the chat completion. Optional.

Chat Prompt and Completion Data

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

Spring AI supports exporting chat prompt and completion data as span events if you use an OpenTelemetry tracing backend, whereas data is exported as span attributes if you use an OpenZipkin tracing backend.

Furthermore, Spring AI supports logging chat prompt and completion data, useful for troubleshooting scenarios.

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

プロパティ	説明	デフォルト
`spring.ai.chat.observations.include-prompt`	Include the prompt content in observations. `true` or `false`	`false`
`spring.ai.chat.observations.include-completion`	Include the completion content in observations. `true` or `false`	`false`
`spring.ai.chat.observations.include-error-logging`	Include error logging in observations. `true` or `false`	`false`

spring.ai.chat.observations.include-prompt

Include the prompt content in observations. true or false

false

spring.ai.chat.observations.include-completion

Include the completion content in observations. true or false

false

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

Include error logging in observations. true or false

false

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

EmbeddingModel

Observability features are currently supported only for EmbeddingModel implementations from the following AI model providers: Azure OpenAI, Mistral AI, Ollama, and OpenAI. Additional AI model providers will be supported in a future release.

The gen_ai.client.operation observations are recorded on embedding model method calls. They measure the time spent on method completion and propagate the related tracing information.

The gen_ai.client.token.usage metrics measures number of input and output tokens used by a single model call.

表 8: 低カーディナリティキー
名前	説明
`gen_ai.operation.name`	実行される操作の名前。
`gen_ai.system`	クライアントインストルメンテーションによって識別されるモデルプロバイダー。
`gen_ai.request.model`	リクエストが行われているモデルの名前。
`gen_ai.response.model`	レスポンスを生成したモデルの名前。

表 9: 高カーディナリティキー
名前	説明
`gen_ai.request.embedding.dimensions`	The number of dimensions the resulting output embeddings have.
`gen_ai.usage.input_tokens`	The number of tokens used in the model input.
`gen_ai.usage.total_tokens`	The total number of tokens used in the model exchange.

For measuring user tokens, the previous table lists the values present in an observation trace. Use the metric name gen_ai.client.token.usage that is provided by the EmbeddingModel.

イメージモデル

Observability features are currently supported only for ImageModel implementations from the following AI model providers: OpenAI. Additional AI model providers will be supported in a future release.

The gen_ai.client.operation observations are recorded on image model method calls. They measure the time spent on method completion and propagate the related tracing information.

The gen_ai.client.token.usage metrics measures number of input and output tokens used by a single model call.

表 10: 低カーディナリティキー
名前	説明
`gen_ai.operation.name`	実行される操作の名前。
`gen_ai.system`	クライアントインストルメンテーションによって識別されるモデルプロバイダー。
`gen_ai.request.model`	リクエストが行われているモデルの名前。

表 11: 高カーディナリティキー
名前	説明
`gen_ai.request.image.response_format`	The format in which the generated image is returned.
`gen_ai.request.image.size`	The size of the image to generate.
`gen_ai.request.image.style`	The style of the image to generate.
`gen_ai.response.id`	AI レスポンスの一意の識別子。
`gen_ai.response.model`	レスポンスを生成したモデルの名前。
`gen_ai.usage.input_tokens`	モデル入力 (プロンプト) で使用されるトークンの数。
`gen_ai.usage.output_tokens`	The number of tokens used in the model output (generation).
`gen_ai.usage.total_tokens`	The total number of tokens used in the model exchange.
`gen_ai.prompt`	The full prompt sent to the model. Optional.

For measuring user tokens, the previous table lists the values present in an observation trace. Use the metric name gen_ai.client.token.usage that is provided by the ImageModel.

表 12: イベント
名前	説明
`gen_ai.content.prompt`	Event including the content of the image prompt. Optional.

Image Prompt Data

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

Spring AI supports exporting image prompt data as span events if you use an OpenTelemetry tracing backend, whereas data is exported as span attributes if you use an OpenZipkin tracing backend.

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

プロパティ	説明	デフォルト
`spring.ai.image.observations.include-prompt`	`true` or `false`	`false`

spring.ai.image.observations.include-prompt

true or false

false

If you enable the inclusion of the image prompt data in the observations, there’s a risk of exposing sensitive or private information. Please, be careful!

Vector Stores

All vector store implementations in Spring AI are instrumented to provide metrics and distributed tracing data through Micrometer.

The db.vector.client.operation observations are recorded when interacting with the Vector Store. They measure the time spent on the query、add、remove operations and propagate the related tracing information.

表 13: 低カーディナリティキー
名前	説明
`db.operation.name`	The name of the operation or command being executed. One of `add`, `delete`, or `query`.
`db.system`	The database management system (DBMS) product as identified by the client instrumentation. One of `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`	The name of a collection (table, container) within the database.
`db.namespace`	The name of the database, fully qualified within the server address and port.
`db.record.id`	The record identifier if present.
`db.search.similarity_metric`	The metric used in similarity search.
`db.vector.dimension_count`	The dimension of the vector.
`db.vector.field_name`	The name field as of the vector (e.g. a field name).
`db.vector.query.content`	The content of the search query being executed.
`db.vector.query.filter`	The metadata filters used in the search query.
`db.vector.query.response.documents`	Returned documents from a similarity search query. Optional.
`db.vector.query.similarity_threshold`	Similarity threshold that accepts all search scores. A threshold value of 0.0 means any similarity is accepted or disable the similarity threshold filtering. A threshold value of 1.0 means an exact match is required.
`db.vector.query.top_k`	The top-k most similar vectors returned by a query.

表 15: イベント
名前	説明
`db.vector.content.query.response`	Event including the vector search response data. Optional.

Response Data

The vector search response data is typically big and possibly containing sensitive information. For those reasons, it is not exported by default.

Spring AI supports exporting vector search response data as span events if you use an OpenTelemetry tracing backend, whereas data is exported as span attributes if you use an OpenZipkin tracing backend.

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

プロパティ	説明	デフォルト
`spring.ai.vectorstore.observations.include-query-response`	`true` or `false`	`false`

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

true or false

false

If you enable the inclusion of the vector search response data in the observations, there’s a risk of exposing sensitive or private information. Please, be careful!