설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
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 SpringTransactionPort 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.