5.9 KiB
title, source_type, url, archive_url, status, confidence, tags, related_branches, related_projects, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_branches | related_projects | created | last_reviewed | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| official-doc / datasource-micrometer — JDBC Observation API for Spring Boot 3 (net.ttddyy.observation) | official-doc | https://jdbc-observations.github.io/datasource-micrometer/docs/current/docs/html/ | raw | high |
|
|
2026-06-09 | 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.querymetric 은 histogram 으로 P50/P95/P99 latency 알럿 설정 가능 (APM 필요)- 이 방식은 "임계값 초과 시 로그" 보다 "latency distribution 추적" 에 더 적합한 use case