- 결정 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>
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.