93 lines
5.9 KiB
Markdown
93 lines
5.9 KiB
Markdown
---
|
|
title: official-doc / datasource-micrometer — JDBC Observation API for Spring Boot 3 (net.ttddyy.observation)
|
|
source_type: official-doc
|
|
url: https://jdbc-observations.github.io/datasource-micrometer/docs/current/docs/html/
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [backend, db, jdbc, micrometer, observability, tracing, spring-boot-3]
|
|
related_branches: [feature-database-connection-pool-contract]
|
|
related_projects: []
|
|
created: 2026-06-09
|
|
last_reviewed: 2026-06-09
|
|
---
|
|
|
|
# datasource-micrometer — JDBC Observation API for Spring Boot 3
|
|
|
|
> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-database-connection-pool-contract]] | Micrometer/OpenTelemetry 기반 JDBC 관측 방식(span/metric)의 슬로우 쿼리 탐지 가능성 및 파라미터 노출 기본 동작 근거 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://jdbc-observations.github.io/datasource-micrometer/docs/current/docs/html/
|
|
- 보조 URL: https://github.com/jdbc-observations/datasource-micrometer
|
|
- 저자 / 조직: Tadaya Tsuyukubo (net.ttddyy.observation) — datasource-proxy 와 동일 저자
|
|
- 마지막 확인일: 2026-06-09
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`feature-database-connection-pool-contract` 브랜치에서 Micrometer Observation API 기반 JDBC 추적 방식을 슬로우 쿼리 탐지 대안으로 검토. 핵심 질문: (1) statement-level 슬로우 쿼리 탐지가 가능한가, (2) 파라미터 값이 span/tag 에 기본 포함되는가, (3) 임계값 알럿 방식인가 메트릭 기반인가.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> "Query observations: Execute span with timer metrics (jdbc.query)"
|
|
|
|
— datasource-micrometer docs (생성 observation 타입)
|
|
|
|
> "jdbc.datasource-proxy.slow-query.enable-logging=true"
|
|
> "jdbc.datasource-proxy.slow-query.threshold (default 300 seconds)"
|
|
|
|
— datasource-micrometer docs (슬로우 쿼리 로그 설정)
|
|
|
|
> "Bind parameters are not included by default. Users must explicitly enable this feature via: listener.setIncludeParameterValues(true) or Spring Boot property: jdbc.datasource-proxy.include-parameter-values=true"
|
|
|
|
— datasource-micrometer docs (파라미터 포함 opt-in 방식)
|
|
|
|
> "When OpenTelemetry semantic conventions are enabled, queries undergo analysis and can be sanitized or summarized through JSqlParser."
|
|
|
|
— datasource-micrometer docs (OpenTelemetry 연동 시 SQL sanitization 가능)
|
|
|
|
> "Instrumentation operates at statement-level granularity, not method-level"
|
|
|
|
— datasource-micrometer docs (개별 쿼리 실행 단위 추적)
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| C1 | datasource-micrometer 는 JDBC 쿼리 실행 시간을 `jdbc.query` metric 과 span 으로 기록한다 | "Query observations: Execute span with timer metrics (jdbc.query)" | `official-vendor-doc` | datasource-micrometer + Spring Boot 3 자동 구성 환경 | 임계값 기반 로그 알럿이 기본 제공된다는 주장 반증 |
|
|
| C2 | 기본 설정에서 바인드 파라미터 값은 span/tag 에 포함되지 않으며 opt-in 으로만 활성화된다 | "Bind parameters are not included by default. Users must explicitly enable this feature via: listener.setIncludeParameterValues(true)" | `official-vendor-doc` | datasource-micrometer 1.x Spring Boot 3 환경 | 파라미터가 기본 로깅된다는 주장 반증 |
|
|
| C3 | 슬로우 쿼리 로그 임계값은 `jdbc.datasource-proxy.slow-query.threshold` 로 설정하며 기본값은 300초이다 | "jdbc.datasource-proxy.slow-query.threshold (default 300 seconds)" | `official-vendor-doc` | datasource-micrometer Spring Boot 통합 환경 | — |
|
|
| C4 | OpenTelemetry 연동 시 JSqlParser 를 통해 SQL sanitization (파라미터 제거/추상화) 이 가능하다 | "queries undergo analysis and can be sanitized or summarized through JSqlParser" | `official-vendor-doc` | OTel semantic convention 모듈 사용 환경 | sanitization 이 기본 활성화된다는 주장 반증 |
|
|
| C5 | 추적 단위는 statement-level 이며 repository method-level 이 아니다 | "Instrumentation operates at statement-level granularity, not method-level" | `official-vendor-doc` | datasource-micrometer 1.x | repository 메서드 단위로 느린 쿼리를 특정할 수 있다는 주장 반증 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `C1~C5`: datasource-micrometer 의 metric/span 생성, 파라미터 기본 비포함, 슬로우 쿼리 설정 방식
|
|
- 이 자료가 증명하지 않는 것:
|
|
- APM (Datadog, Grafana 등) 연동 없이 단독으로 슬로우 쿼리 알럿이 가능하다는 주장
|
|
- metric 기반 탐지(P99 latency 초과)가 log 기반 탐지보다 우월하다는 주장
|
|
- 운영 환경에서 span 수집 오버헤드가 무시할 수준이라는 주장
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- APM 백엔드(Prometheus + Grafana, Datadog 등) 의 존재 여부 확인
|
|
- `jdbc.datasource-proxy.slow-query.threshold` 기본값 300초를 프로젝트 요구사항(1초)에 맞게 변경 필요
|
|
- datasource-micrometer 가 내부적으로 datasource-proxy 를 사용함 — 중복 의존성 검토
|
|
|
|
## 메모 / Notes
|
|
|
|
- datasource-micrometer 는 datasource-proxy 를 기반으로 Micrometer Observation API 를 래핑한 라이브러리 — datasource-proxy 의 슬로우 쿼리 기능을 내부적으로 재사용
|
|
- `jdbc.query` metric 은 histogram 으로 P50/P95/P99 latency 알럿 설정 가능 (APM 필요)
|
|
- 이 방식은 "임계값 초과 시 로그" 보다 "latency distribution 추적" 에 더 적합한 use case
|
|
|
|
## Related / 관련
|
|
|
|
- [[raw/official-docs/datasource-proxy-slow-query-official]]
|
|
- [[raw/official-docs/hibernate-slow-query-log-official]]
|
|
- 이 자료를 인용한 wiki 요약: (미생성)
|