OpenTelemetry Collector 0.163.0 큐 수정과 xhash 변경 적용 가이드

Collector v0.163.0의 exporter 큐 수정 조건을 점검하고 xhash 값 변경과 mdatagen 생성 정책을 커스텀 배포에 반영한다.

2026-10-26

큐 수정과 해시 변경은 검증 기준이 다르다

block_on_overflow를 켠 exporter 큐와 xhash를 직접 사용하는 코드는 이번 업데이트에서 서로 다른 검증이 필요하다. 큐는 문제가 발생했던 조건을 재현해 진행 여부를 확인해야 하고, 해시는 기존 출력값과의 일치를 기대하던 기준을 다시 검토해야 한다.

기준 릴리스는 **OpenTelemetry Collector v0.163.0 (2026-10-14)**이다. 공식 릴리스 노트는 대기 중인 offer의 취소에 따른 큐 데드락 수정, 초과 크기 span·profile의 드롭 범위 수정, xhash의 전체 해시값 변경을 명시한다. 커스텀 배포를 만드는 쪽에는 mdatagen의 sending_queue opt-in과 builder의 detector 선택도 검토 대상이다.

운영 점검과 생성 코드 검토를 구분하면 적용 범위를 좁힐 수 있다. 다음 표의 조건에 해당하는 곳부터 확인한다.

변경 대상 해당 조건 적용 후 확인할 것
exporter 큐 block_on_overflow가 켜져 있고 대기 중인 offer가 취소됨 해당 취소 조건에서 큐가 데드락에 빠지지 않는지
traces·profiles 배치 분할 초과 크기 span 또는 profile이 포함됨 해당 항목 뒤의 span·profile까지 함께 버려지지 않는지
xhash 해시값을 직접 사용하거나 기대값으로 검증함 전체 해시값 변경을 검증 기준에 반영했는지
mdatagen exporter의 metadata.yaml과 생성 코드를 관리함 sending_queue 선언 여부에 따른 생성 결과
builder 배포판의 resource detection detector 구성을 관리함 선택한 detector 집합이 생성된 Go build tags에 반영되는지

아래 그림은 각 변경이 요구하는 검증의 방향을 구분한다.

⤢✕v0.163.0 적용 검토exporter 큐xhash커스텀 배포대기 중인 offer 취소초과 크기 span·profile데드락 수정 검증드롭 범위 검증전체 해시값 변경 반영sending_queue 선언 검토detector 선택 검토

큐 데드락은 대기 중인 offer의 취소 조건으로 확인한다

pkg/exporterhelper의 데드락 수정은 block_on_overflow가 활성화된 상태에서 대기 중인 offer가 취소되는 경우를 대상으로 한다. 큐가 가득 찼다는 조건만으로 릴리스 노트에 적힌 문제를 검증했다고 볼 수는 없다. 취소가 수정 대상 조건에 포함돼 있기 때문이다.

이 설정을 사용하는 파이프라인에서는 기존 큐 검증에 대기 중인 offer의 취소 상황이 들어 있는지 확인한다. 없다면 해당 조건을 검증 항목에 추가하고, 취소 이후 큐가 데드락에 빠지지 않는지를 관찰한다. 단순히 시작에 성공하거나 정상 부하에서 데이터를 내보냈다는 결과만으로 이 수정의 효과를 판단하지 않는다.

반대로 릴리스 노트는 모든 큐 정지 문제나 모든 overflow 상황을 해결했다고 설명하지 않는다. 업데이트 판단과 검증 기록에도 수정 조건을 그대로 남기는 편이 정확하다. 예를 들어 “큐 문제 해결”보다 “block_on_overflow 활성화 상태에서 대기 중인 offer 취소 조건 검증”이라고 기록하면 이후 문제가 생겼을 때 확인 범위가 분명해진다.

초과 크기 항목 뒤의 데이터가 함께 버려지는지 본다

배치 분할 수정의 핵심은 드롭되는 범위다. 이전에는 초과 크기 profile이나 span을 처리하면서 그 뒤에 대기하던 profile 또는 span까지 버리는 문제가 있었다. v0.163.0에서는 초과 크기 항목만 드롭하도록 수정됐다.

이 변경을 검증할 때는 초과 크기 항목 자체의 드롭 여부만 보면 부족하다. 그 항목이 드롭되는 것은 수정 후에도 남는 동작이다. 확인해야 할 차이는 뒤따르는 항목까지 함께 버려지는가에 있다.

traces와 profiles를 모두 다룬다면 각각 확인한다. 초과 크기 span 뒤의 span이 함께 버려지지 않는지, 초과 크기 profile 뒤의 profile이 함께 버려지지 않는지를 검증 기준으로 둔다. 릴리스 노트에는 구체적인 크기 임계값이 없으므로 이 변경만을 근거로 임계값을 정하거나 조정할 수는 없다.

아래 그림은 traces와 profiles에 공통으로 적용되는 드롭 범위의 차이를 보여 준다.

⤢✕초과 크기 span·profile과뒤따르는 항목수정 전v0.163.0초과 크기 항목 드롭뒤따르는 항목도 함께 드롭초과 크기 항목만 드롭뒤따르는 항목은 함께 드롭하지않음

이 수정은 초과 크기 항목을 전송할 수 있게 만드는 변경이 아니다. 운영 검증에서는 초과 크기 항목의 처리와 그 뒤 데이터의 처리를 구분해 결과를 남겨야 한다.

xhash는 기존 해시값과의 일치를 기대하지 않는다

pkg/xpdata의 xhash 수정은 서로 다른 맵이 같은 해시를 만들던 문제를 다룬다. 키·문자열·바이트에 길이 접두를 붙이는 방식으로 수정됐으며, 릴리스 노트는 xhash가 만드는 모든 해시값이 바뀐다고 명시한다.

따라서 xhash를 직접 사용하는 코드에서는 “문제가 있던 입력만 결과가 바뀐다”는 가정으로 업데이트하면 안 된다. 기존 해시값을 기대값으로 둔 테스트가 있다면 그 기대값의 목적부터 확인한다. 이전 구현의 출력과 일치하는지를 검사하는 것인지, 서로 다른 입력을 구분하려는 동작을 검사하는 것인지에 따라 검토할 내용이 달라진다.

기존 출력값을 저장하거나 비교하는 사용처가 있다면, 그 사용처에서 버전 변경 전후의 해시값을 어떻게 취급하는지도 확인해야 한다. 이는 모든 Collector 파이프라인에 그런 사용처가 있다는 뜻이 아니라, xhash를 직접 사용하는 경우의 점검 항목이다. 제공된 자료만으로는 개별 배포의 해시 사용 위치나 저장 방식까지 판단할 수 없다.

큐 수정과 해시 변경을 하나의 성공 기준으로 묶지 않는 것도 필요하다. 큐 검증은 특정 조건에서 멈추거나 과도하게 드롭하던 동작이 수정됐는지 확인하는 작업이다. xhash 검증은 출력값이 바뀐다는 계약을 사용처가 받아들였는지 확인하는 작업이다.

mdatagen은 exporter별 opt-in 상태를 확인한다

cmd/mdatagen은 metadata.yaml의 sending_queue 필드에 opt-in한 exporter에 대해 queue/batch sender 기본값을 생성한다. 선언을 생략한 exporter는 명시적으로 참여하기 전까지 영향을 받지 않는다. 릴리스 노트는 이를 마이그레이션 Phase 2에서 exporter별로 참여하는 방식으로 설명하며, batching migration RFC를 연결한다.

커스텀 exporter를 관리한다면 생성기를 업데이트했다는 사실과 exporter가 opt-in했다는 사실을 구분해야 한다. 먼저 metadata.yaml에 sending_queue 선언이 있는지 확인하고, 그 선언 여부를 기준으로 생성 결과를 검토한다. 필드가 없는 exporter까지 같은 방식으로 바뀌었다고 가정하지 않는다.

저장소 전체를 감사할 때는 릴리스 노트에 제시된 환경변수를 사용할 수 있다.

MDATAGEN_SENDING_QUEUE_OPT_OUT=true

자료에 설명된 이 값의 효과는 선언하지 않은 모든 exporter에도 표준 기본값을 생성하는 것이다. 변수 이름만 보고 생성 동작을 추측하지 말고, 이 조건에서 나온 생성 결과임을 구분해 검토한다. 제공된 자료에는 생성기 실행 명령이나 sending_queue의 구체적인 YAML 구조가 없으므로 여기서는 별도의 실행 예시를 추가하지 않는다.

아래 비교는 평소 exporter별 검토와 저장소 전체 감사에서 생성 대상을 어떻게 구분해야 하는지 보여 준다.

⤢✕ mdatagen sending_queue 생성 대상 비교 metadata.yaml의 sending_queue 선언 · MDATAGEN_SENDING_QUEUE_OPT_OUT=true 사용 · 생성 동작 비교 축 명시적 opt-in 선언 생략 저장소 전체 감사 metadata.yaml의 sending_queue 선언 MDATAGEN_SENDING_ QUEUE_OPT_OUT=true 사용 생성 동작 있음 없음 없음 사용 조건 없음 미사용 MDATAGEN_SENDING_ QUEUE_OPT_OUT=true 사용 queue/batch sender 기본값 생성 명시적으로 opt-in하기 전까지 영향 없음 선언하지 않은 모든 exporter에 표준 기본값 생성 OpenTelemetry Collector 0.163.0 큐 수정과 xhash 변경 적용 가이드

커스텀 배포판은 detector 선택을 별도로 검토한다

cmd/builder에는 dist.resource.detection.detectors가 추가됐다. 배포판이 resourcedetectionprocessor의 detector를 더 작은 집합으로 선택할 수 있고, 이 선택은 생성된 Go build tags로 반영된다.

배포판을 직접 만드는 경우에는 exporter 생성 정책과 detector 선택을 별도 항목으로 검토한다. sending_queue는 exporter의 queue/batch sender 기본값 생성에 관한 선택이고, dist.resource.detection.detectors는 배포판에 포함할 detector 집합에 관한 선택이다. 같은 릴리스에 들어왔더라도 설정 위치와 확인할 결과가 다르다.

detector 범위를 줄이려는 배포판이라면 필요한 detector 집합을 정한 뒤 builder 설정과 생성된 Go build tags를 대조한다. 릴리스 노트에는 선택 가능한 detector 목록이나 구체적인 설정 예시가 없으므로 이 자료만으로 특정 목록을 권하거나 설정 파일을 완성할 수는 없다.

적용 기록에는 실제로 해당한 변경을 남기면 된다. block_on_overflow 큐의 취소 조건, 초과 크기 항목 뒤의 드롭 범위, xhash 사용처의 기대값, exporter별 opt-in 상태, 배포판의 detector 선택이 각각 확인 대상이다. 이 항목들을 실제 설정과 사용처에 대조하면 v0.163.0의 수정 효과와 호환성 변경을 구분해 검증할 수 있다.

OpenTelemetryCollectorexportersending_queuexhash