Files
clean-architecture-backend-…/docs/jpa/observability.md
T
DongHyeonka b1cda0307b docs(jpa): JPA 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: `docs/jpa`의 문서 12개가 영어였고 `security.md`도 영어 절이 남아 있었다.
`repository-adaptation.md`는 Spring Boot 버전과 leaf 개수를 복사했다(number 예외).
번역하며 대조하니 지금 코드와 다른 주장이 여럿 있었다.

고친 것:
- 13개를 번역했다. 코드·명령·경로·표 구조는 그대로다. `support-matrix.md`의 DB 표와
  gate 표는 `JpaReleaseRendering`이 읽는 모양(`| PostgreSQL 17 | Stable |`,
  `` | `osiv-disabled` | gate | ``)을 그대로 둔다. 절 번호(§1~§5)는 코드가 인용해 그대로다.
- 다른 문서·코드가 영어 절 제목으로 인용하는 곳("Who may change the schema", "Bound the
  lock wait", "Concurrent index builds", "An invalid index exists", "Associations")은
  한국어 제목 뒤 괄호에 영어를 남겼다.
- 코드에 맞춘 주장:
  - support-matrix: 없는 `JpaPlatformAutoConfiguration.capabilities()` →
    `JpaPlatformReport.platformCapabilities()`. COPY 수준은 보고대로 Advanced.
  - repository-adaptation: leaf 개수·Boot 버전 → registry와 `libs.versions.toml`,
    `src/testkit` → `src/testFixtures`, outbox relay `app-bootstrap` →
    `composition:outbox-relay`, 「build-logic이 없다」 → `src/build-logic` convention
    plugin, 없는 `runtime_memberships`, 없는 `JpaDataSourceSettings`, 여러 major 선택은
    `JpaPlatformContractSupport.start()`가 거부한다(`StablePostgreSqlMatrixContractTest`만
    여러 개를 받는다), 이미지는 `container-images.properties`의 digest.
  - experimental-promotion-checklist: 결과 이름은 지운 gate의 것임을 밝혔다.
- 테스트: `JpaDocumentationContractTest`가 H2 단락의 「운영 보장이 아니」·「PostgreSQL 계약
  증거」와 「알려진 빈틈」을 본다. `PoolLaneClaimTest`는 한국어 금지 문구 셋을 더 본다.
  고친 두 테스트의 영어 `@DisplayName`은 AGENTS.md 규칙대로 한국어로 바꿨다.
- 예외 목록에서 JPA language 줄 12개와 number 줄 2개를 지웠다.

버린 대안: H2 단락의 영어 문구를 괄호로 남겨 단언을 그대로 두기. 독자가 읽는 것은
한국어 문장이므로 단언도 그 문장을 붙잡아야 한다.

위험·한계: `PoolLaneClaimTest`의 한국어 금지 문구는 지금 문서를 기준으로 고른 것이라,
다른 말로 쓴 인증 주장은 잡지 못한다. 영어 문구 검사는 그대로 남아 있다.

검증: 최종 트리 기준(첫 커밋 본문 참고).

검증(desktop, 최종 트리 8295db89):
- `:adapter:outbound:persistence-jpa:check` rc=0(666개 실패 0. `JpaDocumentationContractTest` 4,
  `JpaReleaseRenderingTest` 13, `PoolLaneClaimTest` 3), `:mainCheck` rc=0, `testQualityCheck` rc=0.
- RED: 기준 커밋의 옛 문서에 대면 `JpaDocumentationContractTest`의 H2 단락·알려진 빈틈 2개가 실패한다.
  `PoolLaneClaimTest`는 금지 문구를 더한 것이라 옛 영어 문서에서도 통과한다(RED 없음).
2026-11-07 17:56:34 +09:00

3.7 KiB

관측

설계서 §37. 무엇을 재고, 측정에 무엇이 절대 나타나면 안 되나.

기본으로 내는 것

JPA 고유의 것은 없다. 어떤 조립도 플랫폼에 MeterRegistry 기반 observation을 만들지 않고, SpringTransaction은 트랜잭션 메트릭을 기록하지 않는다. 트랜잭션 결과는 JPA meter가 아니라 공유 영속성 오류 코드와 애플리케이션 자신의 메트릭으로 보인다.

이력: 이 문서가 전에 적던 jpa.transaction.* meter(duration, rollback, timeout, completion.unknown)는 JpaTransactionObservation이 만들었는데, 그것을 만드는 곳이 없어서 2026-09-25에 지웠다(docs/capability-status.md).

쿼리 메트릭 — 호출자가 요청할 때만

jpa.query.duration과 jpa.query.rows는 MicrometerQueryObservation이 기록한다. 서비스가 QueryObservation을 받는 라이브러리 executor(JpaStreamExecutor, HibernateBulkDmlExecutor)에 그것을 넘길 때만이다. 기본값은 NoopQueryObservation이다. 걸린 시간뿐 아니라 행도 재는 이유가 있다. 문장 하나를 내고 행 2만 개를 채우는 쿼리는 문장으로는 빠르고 요청으로는 재앙이다. 걸린 시간 메트릭만으로는 그저 느리다고 보고된다.

태그는 늘 상한이 있다

MicrometerQueryObservation이 기록하는 meter는 모두 태그를 정확히 다섯 가진다. persistence unit, operation, query, outcome, failure category(JpaMetricTags)다. 다섯 다 등록된 식별자이고, registry가 아니라 만들 때 LowCardinality가 검증한다. 그래서 상한 없는 값은 대시보드가 안 열릴 때까지 살아남지 않고, 들어온 자리에서 실패한다.

절대 태그가 아닌 것: entity id, tenant id, SQL 파라미터, 예외 메시지, JDBC URL. 하나하나가 상한이 없어서 행마다나 실패마다 시계열을 만든다. 몇은 플랫폼이 로그에서도 빼는 데이터이고, 메트릭 backend는 그것을 로그만큼 오래 저장하고 넓게 내보낸다.

SQL 안의 쿼리 이름

JpaRepositoryFragmentSupport는 등록한 쿼리 이름을 org.hibernate.comment hint로 둔다. Hibernate는 hibernate.use_sql_comments=true일 때만 그것을 SQL에 쓴다. 다른 길은 NamedStatementInspector다. JpaStreamExecutor, JpaKeysetQuerySupport, JpaRepositoryFragmentSupport.observing(..)이 묶은 쿼리 이름을 문장 앞에 붙인다. 둘 다 기본으로 꺼져 있다. 배포는 spring.jpa.properties.hibernate.session_factory.statement_inspector=dev.caskeleton.adapter.outbound.persistence.hibernate.NamedStatementInspector로 inspector를 켠다. 그러면 주석이 pg_stat_activity, auto_explain, slow query 로그로 간다. 그것이 없으면 「어느 엔드포인트가 이 쿼리를 내나」는 코드에서 SQL 조각을 grep해서 답한다.

진단

SqlDiagnosticRedactor.redact(sql)은 문자열 literal, 숫자, 이메일 모양의 모든 것을 지운다. SQL을 곧 로그에 쓸 코드를 위한 도구다. 플랫폼 안의 어떤 것도 그것을 거쳐 SQL을 로그에 쓰지 않는다. 지우기는 일부러 거칠다. 「해롭지 않은」 값을 남기려면 어느 열이 개인정보를 담는지 알아야 한다.

actuator 엔드포인트

jpaplatform은 DB major 버전, provider 버전, 스키마 버전, OSIV 상태, 런타임 역할 검증, capability 수준을 보고한다. JDBC URL, 사용자 이름, SQL, 엔티티 목록은 보고하지 않는다. actuator 엔드포인트는 management 포트에 닿는 누구나 닿을 수 있고, 그 하나하나가 공짜 정찰 답이 된다. 읽기 전용이다. 마이그레이션이나 repair를 일으킬 수 있는 엔드포인트는 HTTP로 드러난 관리 capability가 된다.