GraphQlResolverObservationConvention·GraphQlDataLoaderObservationConvention
bean이 있지만 Spring for GraphQL observation에 붙지 않는다. 그래서
graphql.datafetcher·graphql.dataloader timer는 Spring 기본 tag
(graphql.field.name, graphql.loader.name, graphql.error.type)를 달고,
플랫폼이 정한 schema 좌표·resolver 무게·batch 크기 tag는 아무 지표에도
없다. 두 convention의 tag 이름도 뜻과 맞지 않는다: 무게를
graphql.operation.type으로, batch 크기를 graphql.complexity.bucket으로
단다. graphql.request는 오류가 없거나 복잡도를 세기 전에 끝난 요청에서
error.type·graphql.complexity.bucket을 빼는데, Prometheus registry는
이름이 같고 key 묶음이 다른 meter를 버린다. 먼저 등록된 쪽만 남고
성공이나 실패 한쪽이 /actuator/prometheus에서 사라진다.
Spring의 DataFetcherObservationConvention·DataLoaderObservationConvention을
구현한 adapter 둘(runtime 패키지)을 두고 GraphQlObservationConfiguration이
@ConditionalOnMissingBean으로 등록한다. resolver는 부모 타입과 field
이름으로 schema 좌표(Type.field)를 만들고, 좌표로 이름 붙일 수 없는
field(_Service.sdl 같은 federation field)는 unnamed와 기본 무게로 같은
key를 단다. DataLoader는 등록한 loader 이름, 또는 Spring이
@BatchMapping loader에 붙이는 schema 좌표(Book.author)를 이름으로 쓰고,
둘 다 아니면 unknown이다. graphql.request는 오류가 없으면
error.type=NONE, 복잡도를 세지 않았으면 graphql.complexity.bucket=unknown을
단다. tag 이름을 graphql.resolver.weight·graphql.batch.size.bucket으로
고치고 cardinality 허용 목록, metrics.yaml 세 행(Micrometer가 다는 error
tag 포함), 공개 API 스냅숏을 맞춘다. 응답 path와 batch key는 싣지 않는다.
버린 안: Spring 기본 convention을 두고 registry만 그 tag로 적기. 플랫폼
convention이 죽은 코드로 남고, field 이름만으로는 타입이 다른 같은 이름
field를 가를 수 없다. 기본 convention을 감싸 tag만 더하는 안은
graphql.error.type이 Micrometer의 error tag와 같은 값을 한 번 더 싣는다.
위험: 세 timer의 tag가 바뀐다. 옛 tag로 거른 대시보드·경보는 비고,
docs/upgrade/2026-11-round9-followups.md 1~4행이 옮기는 법을 적는다.
클래스 이름으로 등록한 loader는 unknown 하나로 묶인다. 자기
DataFetcherObservationConvention·DataLoaderObservationConvention bean을
둔 서비스는 그 bean이 그대로 쓰인다.
검증: desktop :adapter:inbound:graphql:check :adapter:inbound:graphql:systemTest
:adapter:inbound:graphql:verifyGraphQlApiSurface, scripts/verify.sh pr.
BREAKING CHANGE: graphql.datafetcher·graphql.dataloader timer의 tag가
graphql.schema.coordinate·graphql.outcome·graphql.resolver.weight와
graphql.dataloader.name·graphql.outcome·graphql.batch.size.bucket으로
바뀐다. graphql.request는 error.type=NONE·graphql.complexity.bucket=unknown을
단다. 두 convention의 tag key도 바뀐다.
Refs: round9 그룹 A 범위 밖 후속 1
문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. web-advanced는
ADMISSION_REFUSED(503), fileserver는 instance·전송 pool 포화까지
TRANSFER_ADMISSION_REJECTED(429 RATE_LIMIT), gRPC는 RATE_LIMIT_EXCEEDED
(RESOURCE_EXHAUSTED, "요청이 너무 잦습니다")였다. client는 자기 빈도 탓인지 서버
포화인지 가를 수 없었다. web은 상태만 아는 모든 503을 REQUEST_TIMEOUT으로 답했다
(§4는 비동기 시간 초과만). §4에 OPERATION_NOT_FOUND가 없었고, fileserver 오류
code 27개 중 23개가 계약 문서에 없었으며 예시가 "data": null을 실었다. fileserver는
Retry-After를 발생만 보고 붙여, 본문이 retryable=false로 좁힌 code에도 헤더가
나갔다. gRPC Javadoc과 graphql 스냅숏 머리말이 지운 이름(WORKLOG_NOT_FOUND, spi)을
적었다.
고른 방법(리뷰 README 6절 ②):
- 공용 OperationalError.SERVER_BUSY(503, TRANSIENT_DEPENDENCY, retryable,
Retry-After 1)를 더했다. registry 행, RetryAfterAdvisor, runbook
server-busy.md를 같이 둔다.
- web-advanced admission 거절, gRPC call admission(UNAVAILABLE), fileserver의
instance permit·직접 다운로드 permit·전송 pool 포화가 이 코드다. fileserver는
같은 이름의 FileserverErrorCode.SERVER_BUSY를 두고, 이름이 같은 code의 뜻이
같은지 FileserverExceptionTest가 이미 본다. 호출자 자기 scope의 동시 전송
초과만 TRANSFER_ADMISSION_REJECTED 429로 남는다.
- 상태만 아는 503은 SERVER_BUSY, AsyncRequestTimeoutException만
REQUEST_TIMEOUT이다(HttpStatusErrorCodes.forException).
- fileserver Retry-After는 본문과 같은 규칙(code와 발생이 모두 retryable)으로
붙인다. 재시도 불가 code인 ATOMIC_PUBLISH_UNSUPPORTED를 표에서 뺐다.
- docs/fileserver/http-contract.md에 오류 code 표 전체를 두고 예시의 data:null을
지웠다. http-contract §4에 OPERATION_NOT_FOUND와 SERVER_BUSY를 적었다.
- decisions 2.3에 결정 ①②③ 행을 더했다.
- 포화 시험의 sleep(200)을 첫 거절 신호로 바꾸고, timeout 시험이 code까지
본다(같은 파일이라 RR9-03-20의 그 부분을 여기서 고친다).
- web-advanced 파일의 spotless 정리(앞 커밋분)를 함께 싣는다.
버린 대안: JOB_EXECUTOR_REJECTED를 재사용 — 백그라운드 job 이름이라 요청 허가
거절을 읽는 client와 runbook을 잘못 이끈다.
위험·한계: 포화 거절로 분기하던 client와 재시도 정책, WebAdvancedError
.ADMISSION_REFUSED를 참조하던 코드, 모든 503을 REQUEST_TIMEOUT으로 보던 client가
바뀐다(upgrade 안내 8·9·13).
BREAKING CHANGE: 서버 포화 코드가 SERVER_BUSY 하나다(web-advanced
ADMISSION_REFUSED 삭제, fileserver instance·pool 포화 429 → 503, gRPC
RESOURCE_EXHAUSTED → UNAVAILABLE). 상태만 아는 503은 SERVER_BUSY다. 할 일은
docs/upgrade/2026-11-round9-contracts.md.
Refs: RR9-03-06, RR9-03-07, RR9-03-11, RR9-03-12, RR9-03-15, RR9-03-16, RR9-03-20
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.
방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.
위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).
검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.