설계: 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>
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 `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.
|