Scarab 진단 현장 테스트 #034 - Prometheus Docker Swarm Label 소스 경계

대상: prometheus/prometheus

이슈: prometheus/prometheus#12244

풀 리퀘스트 (Pull request): prometheus/prometheus#18979

현장 실험 (Field Lab) 기록: Prometheus #12244

이번 현장 테스트는 문서화에 관한 것이었지만, "단순한 문서화"는 아니었습니다.

공개된 이슈는 Prometheus 내의 Docker Swarm 태스크 발견 (task discovery) 메타데이터에 대한 혼란을 보고했습니다.

사용자는 __meta_dockerswarm_container_label_<labelname>이 OCI 이미지 레이블과 같이 실행 중인 컨테이너나 이미지로부터 레이블을 노출할 것으로 기대했습니다.

하지만 관찰된 동작은 달랐습니다.

메타데이터는 존재했지만, 그 소스가 사용자가 기대했던 런타임 컨테이너나 이미지 레이블 표면이 아니었습니다.

이로 인해 이것은 경계 문제 (boundary problem)가 되었습니다:

문서화된 메타데이터 이름이 무엇을 의미하며, 그것이 실제로 나타내는 공개적인 신뢰할 수 있는 소스 (source of truth)는 무엇인가?

현장 실험 (Field Lab) 기록

이 사례에 대한 공개 현장 실험 기록은 여기에 있습니다:

https://github.com/scarab-systems/scarab-field-lab/tree/main/field-tests/prometheus-prometheus-12244

기록에는 공개 이슈, 공개 풀 리퀘스트, 공개 댓글, 수정 범위, 검증 요약 및 비주장 사항 (non-claims)이 포함되어 있습니다.

여기에는 공개 링크, 상태, 검증 및 주장 경계만 포함됩니다. SDS 소스 코드나 비공개 제품 자료는 포함되지 않습니다.

사례 기록은 오직 공개 증거 계층 (public evidence layer)일 뿐입니다.

SDS 결과

SDS는 Docker Swarm 태스크 발견 (task discovery) 주변의 문서화 경계를 드러냈습니다.

중요한 발견은 Prometheus가 새로운 Docker API 호출을 추가해야 한다는 것이 아니었습니다.

서비스 발견 (service discovery)이 이미지 레이블을 검사하기 시작해야 한다는 것도 아니었습니다.

런타임 동작이 변경되어야 한다는 것도 아니었습니다.

발견된 내용은 더 작았습니다:

Prometheus 문서에서는 메타데이터 레이블 (metadata label)을 "컨테이너로부터의 레이블 (labels from the container)"로 합리적으로 해석될 수 있는 방식으로 설명하고 있었던 반면, 공개 코드 경로 (public code path)는 해당 메타데이터를 Swarm 태스크의 컨테이너 스펙 (container spec)으로부터 채웁니다.

이러한 차이는 서비스 디스커버리 (service-discovery) 메타데이터가 운영 계약 (operational contract)으로 사용되기 때문에 중요합니다.

사람들은 이러한 이름들을 대상으로 리레이블링 규칙 (relabeling rules)을 작성합니다.

만약 메타데이터 필드의 출처가 모호하다면, 사용자는 잘못된 곳에서 데이터를 찾거나, 잘못된 것을 설정하거나, 혹은 실제로는 소스 경계 불일치 (source-boundary mismatch)임에도 불구하고 누락된 레이블을 Prometheus의 버그라고 가정할 수 있습니다.

실패 형태 (Failure shape)

실패 형태는 기대치와 출처 사이의 불일치였습니다.

공개된 이슈 (public issue)는 운영자의 합리적인 기대를 설명했습니다:

만약 메타데이터 이름이 container_label이라고 되어 있다면, 이는 실행 중인 컨테이너에서 보이는 레이블이나 이미지로부터 상속된 레이블을 참조할 수도 있습니다.

하지만 Docker Swarm 태스크 디스커버리 (task discovery)는 더 구체적인 출처를 가집니다.

관련 메타데이터는 태스크의 컨테이너 스펙 (container specification)으로부터 채워집니다.

사후에 생각하면 당연하게 들릴 정도로 언어적으로는 충분히 가깝지만, 운영자가 프로덕션 스크레이프 (production scrape) 설정을 디버깅하며 문서를 읽을 때는 충분히 가깝지 않습니다.

이것이 바로 필드 테스트 (field test)에서 이를 런타임 버그 (runtime bug)로 먼저 취급하지 않은 이유입니다.

문제는 동작 계층 (behavior layer)에서 증명되지 않았습니다.

문제는 문구 경계 (wording boundary)에 있었습니다:

문서가 출처를 충분히 구체적으로 명시하지 않았습니다.

경계 (Boundary)

이 필드 테스트에서의 경계는 다음과 같습니다:

Docker Swarm 태스크 메타데이터는 Swarm 태스크 컨테이너 스펙 (Swarm task container spec)으로부터의 레이블과 실행 중인 Docker 컨테이너 또는 이미지의 레이블을 구분해야 합니다.

이것들은 서로 다른 표면 (surfaces)입니다.

일상적인 언어에서는 겹칠 수 있습니다.

심지어 일부 배포 환경에서는 비슷해 보이는 레이블을 포함할 수도 있습니다.

하지만 이들은 동일한 신뢰할 수 있는 단일 출처 (source of truth)가 아닙니다.

서비스 디스커버리 (service discovery)를 위해서, 메타데이터 레이블 이름이 사용자들이 설정을 구축하는 기반이 되기 때문에 이러한 구분은 중요합니다.

만약 문서에서 소스(source)를 암시적으로 남겨둔다면, 사용자는 Docker API 응답과 Prometheus discovery 코드를 통해 동작을 역공학(reverse-engineer)해야만 합니다.

이는 공개 설정 문서(public configuration documentation)로서 바람직한 경계가 아닙니다.

변경 사항

이번 수정은 Prometheus 설정 문서에서의 한 줄짜리 문서 명확화(documentation clarification)입니다.

풀 리퀘스트(pull request)는 여기 있습니다:

https://github.com/prometheus/prometheus/pull/18979

변경 된 공개 파일은 다음과 같습니다:

• docs/configuration/configuration.md

이 수정은 Docker Swarm 태스크 메타데이터 레이블(metadata label)이 Swarm 태스크의 컨테이너 스펙(container spec)에서 온다는 점을 명확히 합니다.

이것이 패치(patch)의 전부입니다.

런타임(runtime) 동작의 변경은 없습니다.

새로운 Docker discovery 로직도 없습니다.

새로운 Docker API 호출도 없습니다.

Prometheus가 이미지 레이블(image labels)을 검사하도록 시도하지도 않았습니다.

단지 이미 존재하는 메타데이터에 대해 더 명확한 공개 계약(public contract)을 제공했을 뿐입니다.

이것이 코드 수정이 아니었던 이유

코드 에이전트(code-agent) 작업의 위험 요소 중 하나는 모든 것이 코드 패치처럼 보이기 시작한다는 점입니다.

이번 현장 테스트는 유용한 반례(counterexample)가 됩니다.

공개된 이슈(issue)는 실재했습니다.

혼란도 실재했습니다.

운영자(operator)의 경험도 실재했습니다.

하지만 수정의 경계(repair boundary)는 문서였습니다.

이것은 중요합니다.

만약 코드 에이전트가 이를 "누락된 레이블"로 취급했다면, 런타임 동작에 손을 댔을 수도 있습니다: 더 많은 Docker 표면을 검사하거나, 새로운 메타데이터 경로를 추가하거나, discovery 동작을 변경하는 식입니다.

그것은 훨씬 더 큰 요구 사항이 되었을 것입니다.

여기서의 좁은 요구 사항은 더 단순합니다:

기존 동작을 더 정확한 소스와 함께 문서화해야 한다는 것입니다.

이러한 절제는 제가 Scarab을 통해 테스트하고 있는 이론의 일부입니다:

수정의 품질은 편집하기 전에 올바른 경계를 찾는 것에 달려 있다는 것입니다.

때때로 올바른 경계는 코드입니다.

때때로 그것은 테스트입니다.

때때로 그것은 문서입니다.

이 경우에는 문서였습니다.

진단 결과가 중요했던 이유

이 현장 테스트의 더 큰 핵심은 문서 한 줄이 바뀌었다는 사실이 아닙니다.

더 중요한 점은 코드 에이전트 (code agent)가 관성 (momentum)에 따라 수정 형태를 결정해서는 안 된다는 것입니다.

에이전트는 다음과 같은 질문에서 시작해서는 안 됩니다:

"무엇을 바꿀 수 있는가?"

대신 다음과 같은 질문에서 시작해야 합니다:

"저장소 (repo)의 공공의 진실 (public truth)이 어디서 불분명해졌는가?"

이번 사례의 경우, 공공의 진실은 서비스 검색 (service-discovery) 메타데이터 레이블 (label)의 의미에 관한 것이었습니다.

실패의 원인은 메타데이터 이름이 존재했기 때문이 아닙니다.

실패의 원인은 그 이름이 독자를 잘못된 소스 (source)로 안내할 수 있었다는 점에 있었습니다.

경계 (boundary)가 명확해지자, 패치 (patch)는 작아졌습니다.

이것이 Scarab이 반복 가능하게 만들고자 하는 패턴입니다:

진실을 찾고,

경계를 찾고,

경계를 패치한다.

검증 (Validation)

수정 사항은 Field Lab에 기록된 관련 공공 체크 항목들을 통해 Prometheus 저장소 (repository)를 대상으로 검증되었습니다.

Field Lab에 기록된 검증 결과:

• go test ./discovery/moby -count=1 통과
• go build ./cmd/prometheus/ 통과
• GO_ONLY=1 make test 통과
• make lint 통과
• make test 통과

이 초안이 작성된 2026년 6월 19일 당시, 공공 풀 리퀘스트 (pull request, PR)는 열려 있었으며 리뷰를 받을 준비가 되어 있었습니다.

공공 상태는 다음과 같습니다:

• PR 오픈됨
• DCO 통과
• Netlify 배포 미리보기 (deploy-preview) 성공 또는 정보 제공
• 업스트림 (upstream) 리뷰 필요

이 현장 보고서는 업스트림 수락을 주장하지 않습니다.

이 보고서는 공공 진단 기록, 국소적인 문서 수정, 그리고 제출된 PR을 주장합니다.

해당 명확화 작업이 업스트림에 포함될지 여부는 메인테이너 (Maintainers)가 결정합니다.

현장 테스트 결과 (Field test result)

결과:

진단 증거 및 문서 수정 제출됨.

현장 테스트를 통해 다음이 생성되었습니다:

• 이슈에서 경계로 이어지는 공공 기록
• 국소적인 문서 패치
• 영향을 받은 저장소에 대한 검증
• 공공 업스트림 PR
• Scarab Field Lab의 공공 상태 기록

패치는 의도적으로 작습니다.

그것이 핵심입니다.

실패의 원인이 소스 경계의 모호함 (source-boundary ambiguity)일 때, 최선의 수정은 소스를 명시적으로 만드는 문장 하나일 수 있습니다.

공공 주장 (Public claim)

이 현장 테스트는 다음과 같은 국소적인 공공 주장을 뒷받침합니다:

SDS는 Prometheus에서 컨테이너 라벨 (container-label) 메타데이터에 더 명확한 소스가 필요했던 Docker Swarm 태스크 발견 (task discovery) 문서의 경계를 식별하였으며, 해당 경계에 대해 사람이 제출한 문서 수정 (documentation repair) 사항이 준비되었습니다.

다음 사항은 주장하지 않습니다:

• Prometheus가 패치 (patch)를 수락했다는 점
• Prometheus가 Docker 이미지 라벨 (image labels)을 검사해야 한다는 점
• Docker Swarm 발견 (discovery) 동작이 변경되었다는 점
• Scarab이 스스로 프로젝트를 수정한다는 점
• SDS의 소스 또는 제품 세부 정보가 공개되어 있다는 점
• 메인테이너 (maintainers)가 Scarab 또는 Field Lab을 지지한다는 점

Field Lab은 이러한 주장들을 분리하여 유지하기 위해 존재합니다.

공개 (Disclosure)

이 현장 보고서는 공개된 현장 테스트 노트, 공개된 이슈 (issue) 및 PR (Pull Request) 기록, 그리고 공개된 Field Lab 기록을 바탕으로 AI 지원 편집을 통해 작성되었습니다. 진단 주장 (diagnostic claim), 수정 경계 (repair boundary), 그리고 최종 문구는 사람이 검토하였습니다.

Scarab Diagnostic Suite는 독점적 (proprietary) 자산입니다. Field Lab은 공개 사례 기록, 이슈 링크, 검증 요약 및 주장 경계만을 공개합니다.

SDS는 증거를 찾습니다. 사람들은 주장을 합니다. 메인테이너는 결정합니다.