- 결정 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>
59 lines
3.4 KiB
Markdown
59 lines
3.4 KiB
Markdown
# 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.
|