Files
clean-architecture-backend-…/docs/jpa/observability.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: 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>
2026-09-25 12:49:07 +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 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.