관측성
관측성 (Observability)
Spring AI는 Spring 생태계의 관측성 기능을 기반으로 AI 관련 작업에 대한 인사이트를 제공해요. 핵심 컴포넌트인 ChatClient(그리고 Advisor), ChatModel, EmbeddingModel, ImageModel, VectorStore에 대해 메트릭(metrics)과 트레이싱(tracing) 기능을 지원하죠.
애플리케이션에서 메트릭과 트레이싱을 켜려면 Spring Boot Metrics와 Spring Boot Tracing 문서를 참고하세요.
참고: low-cardinality 키(값 종류가 적은 키)는 메트릭과 트레이스 양쪽에 추가되고, high-cardinality 키(값 종류가 많은 키)는 트레이스에만 추가돼요.
출처: 공식문서
Chat Client
spring.ai.chat.client observation은 ChatClient의 call() 또는 stream() 연산이 호출될 때 기록돼요. 호출에 걸린 시간을 측정하고 관련 트레이싱 정보를 전파해요.
Low Cardinality Keys
| Name | Description |
|---|---|
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 |
High Cardinality Keys
| Name | Description |
|---|---|
spring.ai.chat.client.advisors |
구성된 채팅 클라이언트 어드바이저 목록 |
spring.ai.chat.client.conversation.id |
채팅 메모리를 쓸 때 대화 식별자 |
spring.ai.chat.client.tool.names |
채팅 클라이언트에 전달된 도구 이름들 |
프롬프트와 완성 데이터
ChatClient의 프롬프트와 완성(completion) 데이터는 보통 크고 민감한 정보를 포함할 수 있어요. 그래서 기본적으로 내보내지 않아요.
Spring AI는 디버깅·트러블슈팅을 돕기 위해 프롬프트와 완성 데이터 로깅을 지원해요.
| Property | Description | Default |
|---|---|---|
spring.ai.chat.client.observations.log-prompt |
채팅 클라이언트 프롬프트 콘텐츠를 로깅할지 여부 | false |
spring.ai.chat.client.observations.log-completion |
채팅 클라이언트 완성 콘텐츠를 로깅할지 여부 | false |
⚠️ 채팅 클라이언트 프롬프트·완성 데이터 로깅을 켜면 민감하거나 개인적인 정보가 노출될 위험이 있어요. 주의하세요!
Chat Client Advisors
spring.ai.advisor observation은 어드바이저가 실행될 때 기록돼요. 어드바이저(내부 어드바이저에 걸린 시간 포함)에 걸린 시간을 측정하고 관련 트레이싱 정보를 전파해요.
Low Cardinality Keys
| Name | Description |
|---|---|
gen_ai.operation.name |
항상 framework |
gen_ai.system |
항상 spring_ai |
spring.ai.advisor.name |
어드바이저 이름 |
spring.ai.kind |
Spring AI의 프레임워크 API 종류: advisor |
High Cardinality Keys
| Name | Description |
|---|---|
spring.ai.advisor.order |
어드바이저 체인에서의 순서 |
Chat Model
참고: OpenAI와 Anthropic 채팅 모델은 둘 다 HTTP 레이어 observation(채팅 모델 레이어 + HTTP 레이어)을 발행하며, 스트리밍 호출에만 한 가지 제한이 있어요. HTTP 레이어 observation은 HTTP 메서드·URI·상태 코드를 담고, 다운스트림 서비스(AI 게이트웨이·프록시·OpenAI 호환 추론 서버)로 wire에
traceparent를 전파해요.동기 호출에서는
okhttp.requestsspan이gen_ai.client.operationspan 아래에 올바르게 중첩돼요. 스트리밍 호출에서는 HTTP span이 기록되긴 하지만 채팅 모델 span의 자식으로는 연결되지 않아요 — SDK의 비동기 스트리밍 경로가 Spring AI의 HTTP 클라이언트를 호출하기 전에ForkJoinPool.commonPool()로 이동하면서, 그 경계에서 호출 스레드의 observation 컨텍스트를 잃어버리거든요.자세한 내용은 OpenAI chat docs와 Anthropic chat docs를 참고하세요.
gen_ai.client.operation observation은 ChatModel의 call 또는 stream 메서드를 호출할 때 기록돼요. 메서드 완료에 걸린 시간을 측정하고 관련 트레이싱 정보를 전파해요.
중요:
gen_ai.client.token.usage메트릭은 단일 모델 호출에서 사용된 입력·출력 토큰 수를 측정해요.
Low Cardinality Keys
| Name | Description |
|---|---|
gen_ai.operation.name |
수행 중인 연산 이름 |
gen_ai.system |
클라이언트 계측(instrumentation)으로 식별된 모델 공급자 |
gen_ai.request.model |
요청이 향하는 모델 이름 |
gen_ai.response.model |
응답을 생성한 모델 이름 |
High Cardinality Keys
| Name | Description |
|---|---|
gen_ai.request.frequency_penalty |
모델 요청의 frequency penalty 설정 |
gen_ai.request.max_tokens |
모델이 요청에 대해 생성하는 최대 토큰 수 |
gen_ai.request.presence_penalty |
모델 요청의 presence penalty 설정 |
gen_ai.request.stop_sequences |
모델이 추가 토큰 생성을 멈추는 데 쓰는 시퀀스 목록 |
gen_ai.request.stream |
요청이 스트리밍 모드였는지. true일 때만 존재 |
gen_ai.request.temperature |
모델 요청의 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 |
요청에서 모델에 제공된 도구 정의 목록 |
참고: 사용자 토큰을 측정하려면 위 표는 observation 트레이스에 존재하는 값들을 나열한 거예요.
ChatModel이 제공하는 메트릭 이름gen_ai.client.token.usage를 사용하세요.
채팅 프롬프트와 완성 데이터
채팅 프롬프트와 완성 데이터는 보통 크고 민감할 수 있어요. 그래서 기본적으로 내보내지 않아요.
Spring AI는 트러블슈팅 시나리오에 유용한 채팅 프롬프트·완성 데이터 로깅을 지원해요. 트레이싱이 가능하면 로그에 더 나은 상관관계를 위한 trace 정보가 포함돼요.
| Property | Description | Default |
|---|---|---|
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 |
observation에 오류 로깅 포함. true 또는 false |
false |
⚠️ 채팅 프롬프트·완성 데이터 로깅을 켜면 민감하거나 개인적인 정보 노출 위험이 있어요. 주의하세요!
Tool Calling (도구 호출)
spring.ai.tool observation은 채팅 모델 상호작용 맥락에서 도구 호출을 수행할 때 기록돼요. 도구 호출 완료에 걸린 시간을 측정하고 관련 트레이싱 정보를 전파해요.
Low Cardinality Keys
| Name | Description |
|---|---|
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 |
High Cardinality Keys
| Name | Description |
|---|---|
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는 도구 호출 인자·결과 데이터를 span 속성으로 내보내는 것을 지원해요.
| Property | Description | Default |
|---|---|---|
spring.ai.tools.observations.include-content |
observation에 도구 호출 콘텐츠 포함. true 또는 false |
false |
⚠️ observation에 도구 호출 인자·결과 포함을 켜면 민감하거나 개인적인 정보 노출 위험이 있어요. 주의하세요!
EmbeddingModel
참고: 관측성 기능은 현재 다음 AI 모델 공급자의
EmbeddingModel구현에서만 지원돼요: Mistral AI, Ollama, OpenAI. 추가 공급자는 향후 릴리스에서 지원될 예정이에요.
gen_ai.client.operation observation은 임베딩 모델 메서드 호출에서 기록돼요. 메서드 완료에 걸린 시간을 측정하고 관련 트레이싱 정보를 전파해요.
중요:
gen_ai.client.token.usage메트릭은 단일 모델 호출에서 사용된 입력·출력 토큰 수를 측정해요.
Low Cardinality Keys
| Name | Description |
|---|---|
gen_ai.operation.name |
수행 중인 연산 이름 |
gen_ai.system |
클라이언트 계측으로 식별된 모델 공급자 |
gen_ai.request.model |
요청이 향하는 모델 이름 |
gen_ai.response.model |
응답을 생성한 모델 이름 |
High Cardinality Keys
| Name | Description |
|---|---|
gen_ai.request.embedding.dimensions |
결과 출력 임베딩이 갖는 차원 수 |
gen_ai.usage.input_tokens |
모델 입력에 사용된 토큰 수 |
gen_ai.usage.total_tokens |
모델 교환에 사용된 총 토큰 수 |
참고: 사용자 토큰 측정은 위 표가 observation 트레이스에 존재하는 값들을 나열한 거예요.
EmbeddingModel이 제공하는gen_ai.client.token.usage메트릭을 사용하세요.
Image Model
참고: 관측성 기능은 현재 OpenAI 공급자의
ImageModel구현에서만 지원돼요. 추가 공급자는 향후 릴리스에서 지원될 예정이에요.
gen_ai.client.operation observation은 이미지 모델 메서드 호출에서 기록돼요. 메서드 완료에 걸린 시간을 측정하고 관련 트레이싱 정보를 전파해요.
Low Cardinality Keys
| Name | Description |
|---|---|
gen_ai.operation.name |
수행 중인 연산 이름 |
gen_ai.system |
클라이언트 계측으로 식별된 모델 공급자 |
gen_ai.request.model |
요청이 향하는 모델 이름 |
High Cardinality Keys
| Name | Description |
|---|---|
gen_ai.request.image.response_format |
생성된 이미지가 반환되는 형식 |
gen_ai.request.image.size |
생성할 이미지 크기 (예: 1024x1024) |
gen_ai.request.image.style |
생성할 이미지 스타일 |
이미지 프롬프트 데이터
이미지 프롬프트 데이터는 보통 크고 민감할 수 있어요. 그래서 기본적으로 내보내지 않아요.
Spring AI는 트러블슈팅에 유용한 이미지 프롬프트 데이터 로깅을 지원해요. 트레이싱이 가능하면 로그에 trace 정보가 포함돼요.
| Property | Description | Default |
|---|---|---|
spring.ai.image.observations.log-prompt |
이미지 프롬프트 콘텐츠 로깅. true 또는 false |
false |
⚠️ 이미지 프롬프트 데이터 로깅을 켜면 민감하거나 개인적인 정보 노출 위험이 있어요. 주의하세요!
Vector Stores
Spring AI의 모든 vector store 구현은 Micrometer를 통해 메트릭과 분산 트레이싱 데이터를 제공하도록 계측돼 있어요.
db.vector.client.operation observation은 Vector Store와 상호작용할 때 기록돼요. query, add, remove 연산에 걸린 시간을 측정하고 관련 트레이싱 정보를 전파해요.
Low Cardinality Keys
| Name | Description |
|---|---|
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 |
High Cardinality Keys
| Name | Description |
|---|---|
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 |
쿼리가 반환하는 top-k 가장 유사한 벡터 |
응답 데이터
벡터 검색 응답 데이터는 보통 크고 민감할 수 있어요. 그래서 기본적으로 내보내지 않아요.
Spring AI는 트러블슈팅에 유용한 벡터 검색 응답 데이터 로깅을 지원해요. 트레이싱이 가능하면 로그에 trace 정보가 포함돼요.
| Property | Description | Default |
|---|---|---|
spring.ai.vectorstore.observations.log-query-response |
벡터 스토어 쿼리 응답 콘텐츠 로깅. true 또는 false |
false |
⚠️ 벡터 검색 응답 데이터 로깅을 켜면 민감하거나 개인적인 정보 노출 위험이 있어요. 주의하세요!
더 많은 메트릭 참조
이 섹션은 Spring AI 컴포넌트가 Prometheus에 나타나는 대로 내보내는 메트릭을 문서화해요.
메트릭 이름 규칙
Spring AI는 Micrometer를 사용해요. 기본 메트릭 이름은 점을 쓴다(예: gen_ai.client.operation)가 Prometheus에서는 밑줄과 표준 접미사로 내보내져요:
- 타이머(Timers) →
<base>_seconds_count,<base>_seconds_sum,<base>_seconds_max, 그리고 (지원 시)<base>_active_count - 카운터(Counters) →
<base>_total(단조 증가)
참고: 기본 메트릭 이름이 Prometheus 시계열로 어떻게 확장되는지 보여줘요.
Base metric name Exported time series gen_ai.client.operationgen_ai_client_operation_seconds_count,gen_ai_client_operation_seconds_sum,gen_ai_client_operation_seconds_max,gen_ai_client_operation_active_countdb.vector.client.operationdb_vector_client_operation_seconds_count,db_vector_client_operation_seconds_sum,db_vector_client_operation_seconds_max,db_vector_client_operation_active_count
참고 자료
- OpenTelemetry — Semantic Conventions for Generative AI (overview)
- Micrometer — Naming Meters
Chat Client 메트릭
| Metric Name | Type | Unit | Description |
|---|---|---|---|
gen_ai_chat_client_operation_seconds_sum |
Timer | seconds | ChatClient 연산(call/stream)에 걸린 총 시간 |
gen_ai_chat_client_operation_seconds_count |
Counter | count | 완료된 ChatClient 연산 수 |
gen_ai_chat_client_operation_seconds_max |
Gauge | seconds | ChatClient 연산의 최대 관찰 시간 |
gen_ai_chat_client_operation_active_count |
Gauge | count | 현재 진행 중인 ChatClient 연산 수 |
Active vs Completed: *_active_count는 진행 중인 호출을, _seconds_* 계열은 완료된 호출만 반영해요.
Chat Model 메트릭 (모델 공급자 실행)
| Metric Name | Type | Unit | Description |
|---|---|---|---|
gen_ai_client_operation_seconds_sum |
Timer | seconds | 채팅 모델 연산 실행에 걸린 총 시간 |
gen_ai_client_operation_seconds_count |
Counter | count | 완료된 채팅 모델 연산 수 |
gen_ai_client_operation_seconds_max |
Gauge | seconds | 채팅 모델 연산의 최대 관찰 시간 |
gen_ai_client_operation_active_count |
Gauge | count | 현재 진행 중인 채팅 모델 연산 수 |
토큰 사용량
| Metric Name | Type | Unit | Description |
|---|---|---|---|
gen_ai_client_token_usage_total |
Counter | tokens | 토큰 타입별로 라벨링된 총 소비 토큰 |
라벨
| Label | Meaning |
|---|---|
gen_ai_token_type=input |
모델로 보내진 프롬프트 토큰 |
gen_ai_token_type=output |
모델이 반환한 완성 토큰 |
gen_ai_token_type=total |
입력 + 출력 |
Vector Store 메트릭
| Metric Name | Type | Unit | Description |
|---|---|---|---|
db_vector_client_operation_seconds_sum |
Timer | seconds | vector store 연산(add/delete/query)에 걸린 총 시간 |
db_vector_client_operation_seconds_count |
Counter | count | 완료된 vector store 연산 수 |
db_vector_client_operation_seconds_max |
Gauge | seconds | vector store 연산의 최대 관찰 시간 |
db_vector_client_operation_active_count |
Gauge | count | 현재 진행 중인 vector store 연산 수 |
라벨
| Label | Meaning |
|---|---|
db_operation_name |
연산 타입 (add, delete, query) |
db_system |
벡터 DB/공급자 (redis, chroma, pgvector, …) |
spring_ai_kind |
vector_store |
Active vs Completed 이해하기
- Active (
*_active_count) — 진행 중인 연산의 순간 게이지(동시성/부하). - Completed (
*_seconds_sum|count|max) — 완료된 연산의 통계:_seconds_sum / _seconds_count→ 평균 레이턴시_seconds_max→ 마지막 스크랩 이후의 최고점(registry 동작에 따라 다름)
더 알아보기
- 관측·메모리·RAG 어드바이저 → Advisors API
- 채팅 메모리의 대화 식별자·구성 → Chat Memory
- 도구 호출 관측 → Tool Calling