Files
clean-architecture-backend-…/docs/upgrade
DongHyeonka e69c321eca fix(graphql)!: GraphQL 지표에 플랫폼 tag를 붙이고 key 묶음을 고정한다
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
2026-11-13 19:30:12 +09:00
..