Files
clean-architecture-backend-…/docs/jpa/observability.md
T
donghyeon-kaandClaude Opus 5.5 0579935746 review-followup Wave 3 라운드 3(P28·P29): fileserver use case·file:* 권한, 보안 파일 primitive 공용화, jvm-test-suite
- 결정 32: fileserver transport 연산 21개를 `port.in` use case로, 쓰기·읽기에 `file:*` 권한(소유자·tenant 정책은 유지),
  inbound 서비스 이름 `*UseCase`, port 구현 이름 `<Tech><Port>` 규칙(S2-#13b, 24개)
- 디렉터리 descriptor 파일 primitive를 `adapter:outbound:support`로(S4-lead-2 일부 — fileserver는 번역만),
  persistence-fileserver를 scan·클래스별 조건 대신 명시적 `@Bean` 설정으로(S2-#8a 일부), `FileVerifier`를 adapter로
- 호출자 0인 `poster.image-attached` 이벤트 삭제, SES SDK client를 레지스트리 종료 때 close, fileserver migration V1–V5 고정
- P29: auxiliary 레인 → Gradle `jvm-test-suite`(BUILD-O3-5, build-logic 16,768 → 5,851줄), redis-sdk가 runtime을 api로(P22-new-3)
- 통합: JPA API surface 기준선 재승인(이름 규칙 변경), migration lane에 V19 반영, messaging 통합 테스트가 jar 안 migration 목록 조회(ORCH-new-5)
- P28·P29 에이전트가 세션 재시작으로 중단 — 커밋된 것만 합치고 결과 파일은 오케스트레이터가 확정, S6-#10a는 P30으로

검증: ./gradlew ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck architectureCheck verifyPublicPathSnapshot
:app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest
:sample-portfolio:systemTest integrationCheck · -p build-logic test · -p optional-platforms ci · releaseCheck qualificationBootJar 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 14:54:06 +09:00

3.4 KiB

Observability

Design §37. What is measured, and what must never appear in a measurement.

What is emitted by default

Nothing JPA-specific. No composition constructs a MeterRegistry-backed observation for the platform, and SpringTransaction records no transaction metric. The jpa.transaction.* meters this page used to list (duration, rollback, timeout, completion.unknown) were produced by JpaTransactionObservation, which nothing constructed; it was removed on 2026-09-25 (docs/capability-status.md). Transaction outcomes are visible through the shared persistence error codes and the application's own metrics, not through a JPA meter.

Query metrics — only when the caller asks

jpa.query.duration and jpa.query.rows are recorded by MicrometerQueryObservation, and only when a service passes it to a library executor that accepts a QueryObservation (JpaStreamExecutor, HibernateBulkDmlExecutor). The default is NoopQueryObservation. Rows are measured as well as duration because a query that issues one statement and hydrates twenty thousand rows is fast per statement and catastrophic per request — a duration metric alone reports it as merely slow.

Bounded tags, always

Every meter MicrometerQueryObservation records carries exactly five tags: persistence unit, operation, query, outcome, failure category (JpaMetricTags). All five are registered identifiers, validated by LowCardinality at construction rather than at the registry — so an unbounded value fails where it was introduced instead of surviving until a dashboard stops loading.

Never a tag: entity id, tenant id, SQL parameter, exception message, JDBC URL. Each is unbounded, so each creates a time series per row or per failure; several are also the data the platform keeps out of logs, which a metrics backend would store just as durably and export just as widely.

Query names in SQL

JpaRepositoryFragmentSupport sets the registered query name as the org.hibernate.comment hint; Hibernate writes it into the SQL only when hibernate.use_sql_comments=true. The alternative is NamedStatementInspector, which prefixes a statement with the query name bound by JpaStreamExecutor, JpaKeysetQuerySupport or JpaRepositoryFragmentSupport.observing(..). Neither is on by default: a deployment enables the inspector with spring.jpa.properties.hibernate.session_factory.statement_inspector=dev.caskeleton.adapter.outbound.persistence.hibernate.NamedStatementInspector. The comment then travels into pg_stat_activity, auto_explain, and the slow-query log. Without it, "which endpoint issues this query" is answered by grepping the codebase for fragments of SQL.

Diagnostics

SqlDiagnosticRedactor.redact(sql) removes string literals, numbers, and anything email-shaped. It is a utility for code that is about to log SQL; nothing in the platform logs SQL through it. Redaction is blunt on purpose: preserving "harmless" values would require knowing which columns hold personal data.

The actuator endpoint

jpaplatform reports database major version, provider version, schema version, OSIV state, runtime role verification, and capability levels. It reports no JDBC URL, no username, no SQL, and no entity catalog — an actuator endpoint is reachable by anyone who reaches the management port, and each of those would be a free reconnaissance answer. It is read-only: an endpoint that could trigger a migration or a repair would be an admin capability exposed over HTTP.