매핑 충돌로 인한 데이터 스트림 재색인

필드에서 매핑 충돌이 발생하면, 해당 필드가 Elastic Common Schema–표준(ECS-standard)을 따르든 데이터 소스별로 다르든 관계없이 개발자 도구를 사용하여 데이터를 재색인해야 합니다. 이러한 충돌은 데이터 수집 후 다운스트림 기능에 부정적인 영향을 미쳐 부정확한 결과를 초래하거나 시각화, 대시보드, 보안 앱 및 집계와 같은 기능에서 전체 데이터 세트를 사용하지 못하게 할 수 있습니다. 이 블로그 게시물에서는 재색인 프로세스를 자세히 설명합니다.

이 블로그의 콘텐츠는 Elastic 버전 9.2.8 및 8.19.14와 Filestream Integration 버전 2.3.0 및 1.2.0을 사용해 개발 및 검증되었습니다.

중요 사항: 사용 환경에 따라 일부 단계는 특정 수정이 필요할 수 있습니다. 또한 Filestream Integration 버전 2.3.3부터 @package 구성 요소 템플릿에서 동적 템플릿이 제거되었음을 유의하세요.

재색인 프로세스를 시작하기 전에 환경의 현재 저장 공간 할당을 고려하는 것이 중요합니다. 아래에 설명된 단계는 기존 백킹 인덱스의 복사본을 생성하는 과정을 포함하며, 이 복사본은 핫 티어에 임시로 저장됩니다.

Elasticsearch 데이터 계층

• 핫(Hot): 핫 티어는 시계열 데이터의 Elasticsearch 진입점으로, 가장 최근에 자주 검색되는 데이터를 저장합니다. 핫 티어 노드는 빠른 읽기 및 쓰기 속도가 필요하므로 더 많은 리소스와 빠른 저장 공간(SSD)가 필요합니다. 이 티어는 필수이며, 새 데이터 스트림 인덱스는 여기에 자동 할당됩니다.
• 웜(Warm): 시계열 데이터는 핫 티어의 최근 색인된 데이터보다 쿼리 빈도가 낮아지면 웜 티어로 이동할 수 있습니다. 웜 티어에는 일반적으로 최근 몇 주간의 데이터가 저장됩니다. 업데이트는 여전히 허용되지만 빈도는 낮습니다. 웜 티어의 노드는 일반적으로 핫 티어의 노드만큼 빠를 필요는 없습니다. 복원력을 위해 웜 티어의 인덱스는 하나 이상의 복제본을 사용하도록 구성해야 합니다.
• 콜드(Cold): 검색 빈도가 낮은 데이터는 웜 티어에서 콜드 티어로 이동할 수 있습니다. 콜드 티어는 검색 기능은 유지되지만, 검색 속도보다는 저장 공간 비용 절감을 우선시합니다. 또는 콜드 티어에 검색 가능한 스냅샷 대신 복제본이 있는 일반 인덱스를 저장할 수 있습니다. 이를 통해 웜 티어에 비해 디스크 공간 요구 사항을 줄이지 않고도 오래된 데이터에 대해 더 저렴한 하드웨어를 사용할 수 있습니다.
• 프로즌(Frozen):쿼리 빈도가 낮거나 더 이상 쿼리되지 않는 데이터는 남은 수명 주기 동안 콜드 티어에서 프로즌 티어로 이동합니다. 이 티어는 스냅샷 리포지토리와 부분적으로 마운트된 인덱스를 사용하여 데이터를 저장하고 로드하므로 로컬 저장 공간 및 비용을 절감하면서도 검색 기능을 유지합니다. 프로즌 티어에서의 검색은 일반적으로 콜드 티어보다 느립니다. Elasticsearch가 스냅샷 리포지토리에서 프로즌 데이터를 가져와야 할 수 있기 때문입니다. 프로즌 티어 전용 노드를 사용하는 것이 좋습니다.

필수 조건: 충돌이 발생하는 필드를 파악합니다

매핑 충돌이 있는 필드를 확인하려면 Stack Management -> Data view -> logs-*로 이동합니다. (logs-* Data view는 logs- 접두사가 붙은 데이터 중 가장 상위 계층입니다.) 충돌이 있는 경우 노란색 상자가 표시됩니다. 충돌 보기를 클릭하거나 검색 상자 옆의 필드 유형 상자에서 충돌을 선택할 수 있습니다.

노란색 충돌 버튼을 클릭하면 어떤 인덱스가 어떤 매핑 유형과 연관되어 있는지 표시됩니다.

이 상황(필드가 keyword와(과) long로 모두 매핑되는 경우)은 일반적으로 특정 매핑 유형이 관련 데이터 스트림에 대한 구성 요소 템플릿에 정의되기 전에 데이터를 수집했기 때문에 발생합니다. 이러한 경우 Elasticsearch는 동적 템플릿을 기반으로 매핑을 설정하려고 시도합니다.

필드에 적합한 매핑을 결정하려면 해당 필드가 ECS 필드인 경우 ECS 필드 참조를 통한 검증이 필요합니다. 해당 필드가 ECS 필드가 아닌 경우 올바른 매핑을 결정하기 위해 해당 값을 검토해야 합니다.

예시의 log.offset와(과) 같은 필드가 ECS에 문서화되어 있지 않은 경우 다음 단계는 해당 필드의 값을 조사하고, 충돌하는 매핑 유형 중 가장 많은 인덱스를 가진 유형을 확인하고, 다른 인덱스의 구성 요소 템플릿을 검토하는 것입니다.

일반적으로 가장 많은 인덱스와 연결된 매핑 유형이 올바른 유형이지만, 이를 검증하기 위해 해당 필드의 값을 확인하는 것이 좋습니다. 매핑 유형(예: long)의 유효성을 확인하려면 필드 값이 해당 유형에 적합한지도 확인해야 합니다. 이 검증은 Discover를 사용하여 해당 필드를 검색함으로써 수행할 수 있습니다. 동일한 필드를 포함하는 다른 데이터 스트림을 검토하는 것도 추가적인 확인에 도움이 될 수 있습니다.

매핑 문제가 있는 필드의 값을 검토하려면 앞서 언급한 노란색 충돌 버튼으로 돌아가서 충돌 버튼을 클릭하고, 백킹 인덱스 중 하나를 선택한 다음 Discover 세션에 붙여 넣습니다. Kibana 쿼리 언어(KQL) 문은 다음 스크린샷과 같이 _index: 필드 구분 기호를 포함해야 합니다.

새 백킹 인덱스 사용자 정의 구성 요소 템플릿 준비

데이터 스트림의 매핑 충돌을 해결하려면 먼저 관련 @package 구성 요소 템플릿을 살펴봅니다. Stack Management -> 인덱스 관리 -> 구성 요소 템플릿에서 확인할 수 있습니다. 데이터 스트림을 검색하고 해당 @package 링크를 선택합니다. 이 템플릿에는 필드에 대한 매핑이 기본적으로 포함되어 있으며, 매핑 불일치가 발생하는 경우는 흔하지 않지만 더 적절한 유형을 간과할 수 있습니다.

해당 필드에 필요한 필드 중첩 및 매핑이 템플릿에 포함되어 있는지 검토합니다. 예를 들어 템플릿에서 log.offset을(를) keyword(으)로 잘못 표기한 경우 이것이 문제의 원인입니다.

중요: @package/관리형 템플릿을 수정하는 것은 권장되지 않으므로 향후 모든 데이터에 대해 매핑 유형(예: log.offset)을(를) 수정하려면 @custom 구성 요소 템플릿을 사용하거나 생성해야 합니다.

• @package/관리형 템플릿을 수정하는 것은 권장하지 않습니다. 통합을 최신 버전으로 업데이트하면 @package 템플릿에 대한 변경 사항이 덮어쓰여지기 때문입니다. 따라서 @custom 템플릿을 사용하는 것이 좋습니다.
• 데이터 스트림에서 매핑 충돌이 발생하는 경우 누락된 필드(ECS 및 비ECS) 중첩 또는 매핑을 데이터 스트림의 @custom 구성 요소 템플릿에 추가해야 합니다. 이 템플릿이 아직 없는 경우 생성하고 필드에 대한 올바른 매핑 유형을 지정해야 합니다.
• Data view에 여러 충돌이 있는 경우 데이터 스트림에 필요한 모든 누락된 매핑을 동시에 적용하여 재색인을 여러 번 수행하지 않고 한 번만 수행합니다.@custom 구성 요소 템플릿에 적절한 데이터 입력을 위한 항목이 있으면 향후 모든 데이터 수집이 동일한 매핑 지침을 따르게 됩니다.

@custom 구성 요소 템플릿을 생성하거나 사용 중이고 데이터가 채워져 있는지 확인하려면 인덱스 템플릿으로 이동하여 해당 데이터 스트림의 이름을 입력하고 데이터 스트림에서 사용 중인 적절한 @custom 템플릿을 클릭합니다. 템플릿이 아직 생성되지 않은 경우 노란색 상자가 나타나면 UI를 통해 템플릿을 생성할 수 있습니다.

아래 스크린샷은 구성 요소 템플릿 만들기를 선택했을 때 나타나는 다음 페이지입니다. 첫 페이지의 기본 설정을 그대로 두고 매핑 또는 다음을 클릭하여 매핑 페이지에 도달할 때까지 진행합니다.

새로 들어오는 필드에 대한 매핑을 명시적으로 설정하거나 매핑 충돌이 있는 필드를 업데이트하려면, 인덱스 수명 주기 정책에 설정된 구성으로 인해 데이터 스트림이 롤오버될 때 충돌이 발생하는 필드에 대한 항목이 필요합니다.

아래 내용은 파일스트림 데이터 스트림의 @custom 구성 요소 템플릿에서 log.offset 필드의 매핑을 설정합니다. 필요하다면 이 데이터 세트에 대해 사용자 정의 필드를 추가하거나 적합한 매핑으로 @package 에서 필요한 필드를 추가하세요. 이 예에서 오프셋을 Long으로 설정하면 필드 유형은 Numeric이 되고 숫자 유형은 Long이 됩니다. 필드 추가를 클릭한 다음 해당 영역 바깥을 클릭하여 계속 진행하세요.

필요한 필드를 모두 추가했으면 클릭하여 검토하고 준비가 되면 구성 요소 템플릿 만들기 선택합니다. 이 단계부터 수집되는 모든 새 데이터는 log.offset 이(가) long (으)로 설정됩니다.

새 백킹 인덱스 구조 생성

새 백킹 인덱스에는 데이터 스트림의 구성 요소 템플릿과 ECS ecs@mappings 구성 요소 템플릿의 기존 매핑이 모두 포함되어야 합니다. ecs@mappings 구성 요소 템플릿은 이전 구성 요소 템플릿에 포함되지 않았을 수 있는 추가 매핑을 모두 처리하기 위해 데이터 스트림 구성 요소 다음에 적용됩니다.

데이터 스트림의 @package 매핑에 대한 브라우저 탭으로 이동합니다. (Stack Management -> 인덱스 관리 -> 구성 요소 템플릿 -> logs-filestream.generic@package -> 관리 -> 편집으로 이동합니다.) 해당 탭에서 검토 섹션을 클릭한 다음 요청을 클릭하고 마지막으로 오른쪽에 있는 복사 버튼을 클릭합니다. 구성 요소 템플릿의 JSON 콘텐츠를 복사하면 log.offset 필드 매핑을 업데이트하는 동안 나머지 필드 매핑 및 설정이 유지됩니다. 이 JSON은 새로 재색인된 백킹 인덱스의 기본 구조를 형성합니다.

중요: 템플릿의 JSON을 복사하지 않고 재색인 작업을 계속 진행하면 log.offset 충돌은 해결되지만 현재 매핑의 무결성이 유지되지 않아 통합 과정에서 새로운 충돌이 발생하여 원래 문제를 해결하기 위한 이중 작업이 발생하게 됩니다.

두 번째 브라우저 탭을 열고 개발자 도구로 이동한 다음 복사한 콘텐츠를 붙여 넣습니다. 이제 붙여 넣은 내용을 다음과 같이 정리합니다.

요청 수정

1. 인덱스 이름: _component_template/logs-filestream.generic@package 을(를) 재색인하려는 백킹 인덱스의 이름으로 바꾸고 끝에 -1 을(를) 추가합니다. 예를 들어 PUT <backing index to reindex>-1 을(를) 사용합니다.

• 추가된 -1은(는) 재색인을 의미하며 인덱스 생성 날짜를 기준으로 하는 기본 ILM 롤오버 설정과 충돌하지 않습니다.

2. 설정: "template" (3번째 줄)와(과) 전체 JSON 페이로드의 마지막 중괄호를 제거합니다(3번째 줄은 "settings": { (으)로 시작해야 합니다).

• 설정 섹션의 내부 내용을 "index.codec": "best_compression" (으)로 바꿉니다. 이 작업을 수행하면 인덱스 생성 시 Elastic의 최적 압축률이 적용됩니다.
• "index.lifecycle.name": "logs" 에 추가하고 "index.lifecycle.rollover_alias": "" 에 대한 줄도 추가합니다.
  1. "index.lifecycle.name": "logs" 항목은 새 백킹 인덱스에 로그 ILM 정책을 적용합니다. 로그를 사용하지 않는 경우 ILM 정책 이름을 수정합니다.
  2. "index.lifecycle.rollover_alias": "" 은(는) 이 백킹 인덱스가 롤오버되지 않으므로 비어 있지만, 핫 티어 이후 다음 ILM 단계로의 ILM 롤오버 오류를 방지하려면 이 설정이 필요합니다.

3. 구조: 이제 요청에 Settings 섹션과 Mappings 섹션이 모두 포함되어야 합니다. "mappings": { 안에는 "dynamic_templates" 와(과) 하드코딩된 필드와 해당 매핑이 포함된 "properties" 섹션이 있어야 합니다.

4. 동적 템플릿 수정: 현재 동적 템플릿 섹션에는 다음에 ecs@mappings 동적 템플릿이 추가될 때 덮어쓰기될 수 있는 필드에 대한 항목이 포함되어 있어 중복 및 불필요한 추가 줄이 발생합니다.

• "_embedded_ecs-data_stream_to_constant": { (이)라는 제목의 두 번째 섹션을 제외한 "dynamic_templates" 의 모든 섹션을 제거합니다.
• 위에서 설명한 것과 동일한 프로세스를 반복하여 @package 구성 요소 템플릿에 대한 동적 매핑을 수집하되 이번에는 ecs@mappings 구성 요소 템플릿에 대한 동적 매핑을 수집합니다.
  • ecs@mappings 구성 요소 템플릿의 UI에서 매핑의 전체 내용을 복사하여 작업 중인 개발 도구 dynamic_templates 섹션에 붙여 넣고 중복되거나 불필요한 줄을 적절히 제거하는 것이 더 쉬울 수 있습니다. "_embedded_ecs-data_stream_to_constant": { 항목 뒤에 이러한 동적 템플릿 설정 내용을 포함합니다.dynamic_templates 섹션은 개발 도구의 아래 샘플 콘텐츠와 매우 유사해야 합니다.
• 만약 dynamic_templates이(가) 포함되지 않거나 완전히 제거되지 않으면 다른 필드(아래 스크린샷 참조)에 text와(과)keyword이(가) 이중으로 매핑됩니다. 이는 dynamic_templates 섹션이 포함된 경우의 적절한 매핑과 대조됩니다. 남은 부분은 "mappings" 아래의 "properties" 섹션이어야 합니다. 또한 필드가 이중으로 매핑되어 Data view에서 문제가 발생하고(이미 이렇게 매핑되어 있지 않은 경우) 추가적인 매핑 충돌이 발생합니다.

5. 메타데이터 제거: 마지막 섹션( "_meta")와(과) "version" 섹션(있는 경우)을 삭제합니다.

6. 서식 지정: 나머지 섹션을 자동으로 들여쓰고, 성공적인 실행을 방해하는 불필요한 중괄호를 조정하거나 제거합니다.

7. 매핑 변경: "properties" 섹션으로 이동하여 "log" 을(를) 찾은 다음 그 아래에 중첩된 "offset" 을(를) 찾습니다. 유형을 keyword 에서 long (으)로 변경하고 "ignore_above": 1024, (이)라고 표시된 줄 항목(쉼표 포함)을 제거합니다. 이전에 만든 @custom 구성 요소 템플릿에 두 개 이상의 항목이 추가되었다면 여기에 해당 항목을 포함합니다.

이제 개발자 도구 콘솔 화면이 아래 예시와 유사해야 합니다.

콘솔 화면이 예시와 비슷해지면(사용자 환경에 맞는 추가 사용자 정의 필드 및 사용자 정의 값이 포함된 경우), 새 백킹 인덱스의 셸을 생성하는 명령을 실행하고, 일시 중지하여 발생하는 모든 오류를 해결합니다.

재색인 프로세스 시작

새 백킹 인덱스의 기본 구조가 성공적으로 생성되었으므로, 다음 단계는 재색인을 수행하고 매핑 충돌을 해결하는 것입니다.

중요: 매핑 충돌이 발생한 백킹 인덱스가 가장 최근에 생성된 인덱스이고 현재 쓰기 인덱스인 경우(예: 백킹 인덱스의 끝 번호가 -000001인 경우), 데이터 스트림을 롤오버해야 합니다. 현재 문서가 입력되고 있는 쓰기 인덱스는 라이브 백킹 인덱스이므로 수정할 수 없기 때문입니다.

이제 이전에 생성된 @custom 구성 요소 템플릿을 통해 새 쓰기 인덱스에 올바른 필드 매핑이 적용되었으므로 모든 새 문서에 이 변경 사항이 반영됩니다.

이 작업은 다음을 실행하여 수행합니다:

그 예는 다음과 같습니다.

재색인은 기존 백킹 인덱스의 데이터를 동일한 명명 규칙을 사용하는 새 인덱스로 복사하는 작업으로, 일반적으로 필요한 변경 사항을 적용하기 위해 수행됩니다. 이러한 수정 사항에는 구성 요소 템플릿 업데이트 또는 데이터 처리를 위한 새로운 인제스트 파이프라인 추가 등이 포함될 수 있습니다.

다음으로, 잘못된 매핑이 있는 백킹 인덱스에서 새 백킹 인덱스로 데이터가 복사됩니다. 원래 백킹 인덱스는 롤오버되었으므로 더 이상 새 문서를 추가할 수 없습니다. 새 백킹 인덱스는 동일한 명명 규칙을 따르므로 데이터 가시성과 무결성을 유지하면서 올바른 ILM 정책을 적용하지만, 재색인되었음을 나타내는 -1 접미사가 포함됩니다.

필요에 따라 인덱스 이름을 조정하고 다음 코드를 콘솔에 붙여 넣습니다. wait_for_completion=false 을(를) 포함하면 문서 복사 진행 상황을 추적하여 남은 재색인 시간을 추정하는 데 도움이 됩니다. 이 설정이 없으면 아래의 GET _tasks 명령을 사용하여 상태를 추적할 수 없으며 GET <backing index name>-1/_count 을(를) 사용하여 최신 백킹 인덱스의 문서 개수만 확인할 수 있습니다.

중요: 재색인 프로세스 중 문제가 발생하는 경우 재색인 명령을 다시 실행하지 마세요. 다시 실행하면 프로세스가 재시작되고 -1(으)로 끝나는 인덱스에 중복 레코드가 생성됩니다. 다시 시작해야 하는 경우 먼저 끝에 -1이(가) 붙은 인덱스를 삭제한 다음 앞의 PUT 명령을 실행하여 새 백킹 인덱스 셸을 다시 생성하세요.

실행 시 응답에 작업 ID가 포함됩니다. 이 ID를 사용하여 재색인 프로세스를 모니터링할 수 있습니다. GET _tasks/<task ID>

재색인 기간은 원래 인덱스의 데이터 양에 따라 달라집니다. 완료 여부는 GET 명령을 실행할 때 "completed": true을(를) 확인하여 추적할 수 있으며, 두 명령은 유사한 출력을 생성해야 합니다.

GET _tasks/<task ID>

문서 개수에 대한 재색인 프로세스가 완료되었으므로 다음 단계는 새 백킹 인덱스와 해당 특정 필드에 대한 매핑이 올바른지 확인하는 것입니다.

그 예는 다음과 같습니다.

log.offset 에 대한 매핑이 아래와 같이 표시되는지 확인할 수 있습니다. 다른 필드에 단일 매핑 항목만 있는지(text 와(과) keyword 모두 아님) 확인하려면 이전 PUT 명령의 동적 템플릿 섹션에 포함되지 않은 필드와 비교합니다.

재색인 대상인 백킹 인덱스에 문서 개수가 많은 경우 해당 문서가 새 백킹 인덱스로 복사되는 상태를 확인하는 것이 유용합니다. 다음 두 가지 개발자 도구 명령어를 사용하여 문서 개수를 비교함으로써 이를 확인할 수 있습니다.

GET .ds-logs-filestream.generic-default-2026.04.14-000001/_count

GET .ds-logs-filestream.generic-default-2026.04.14-000001-1/_count

개수가 일치하고 올바른 매핑이 있는지 확인되면 데이터 스트림을 업데이트하여 새 백킹 인덱스를 포함시킵니다. 이렇게 하면 인덱스 관리에서 고립된 백킹 인덱스가 생성되어 ILM 정책이 해당 백킹 인덱스에 적용되지 않는 것을 방지할 수 있습니다.

• 성공하면 true라는 확인 응답이 반환됩니다.

다음 명령을 사용하여 새 백킹 인덱스가 추가되었는지 확인하고 ilm_policy이(가) 올바른지 확인합니다.

다음 명령을 사용하여 백킹 인덱스의 ILM 상태를 확인합니다.

• 최근에 생성되었으므로 인덱스가 핫 상태인 것은 정상입니다(8번 또는 10번 줄 검토).

다음을 실행하여 백킹 인덱스를 핫 티어에서 해당 데이터 스트림에 대한 ILM 정책의 핫 단계 이후에 적합한 다음 티어로 전환하세요. 아래 current_step 의 phase, action, name 에 대한 구체적인 값은 위 스크린샷의 11번, 13번, 15번 줄에서 각각 참조할 수 있습니다.

next_step 값은 인덱스가 전환될 다음 ILM 단계 또는 데이터 티어를 나타냅니다.

그 예는 다음과 같습니다.

• 필수는 아니지만, 안전 조치로 백킹 인덱스가 다음 단계로 이동하여 더 이상 핫 티어가 아닌지 확인하기 위해 _ilm/explain 명령을 다시 실행할 수 있습니다.

다음 조건이 충족되면 매핑 충돌이 발생했던 원래 백킹 인덱스를 안전하게 삭제할 수 있습니다.

1. 새 백킹 인덱스가 성공적으로 생성되었습니다.
2. 문서가 새 인덱스로 이동되었으며 문서 수가 일치합니다.
3. 매핑이 수정되었습니다(데이터 스트림 특정 및 ECS 모두).
4. 데이터 스트림에는 새 백킹 인덱스가 통합되었습니다.
5. ILM 정책이 적용되어 인덱스가 핫 단계에서 벗어났습니다.

중요: 또는 원본 인덱스를 삭제하기 전에 Data view 페이지를 확인할 수 있습니다. logs-* 을(를) 선택하고 재색인된 백킹 인덱스(끝자리가 -1인 인덱스)가 long 섹션에 나타나는지 확인합니다. 원본 백킹 인덱스는 여전히 keyword 아래에 있어야 합니다. 재색인된 백킹 인덱스가 long 섹션에 없으면 이전 단계를 다시 검토하고 필요한 수정을 합니다.

그 예는 다음과 같습니다.

충돌을 해결한 후 Data view 페이지로 돌아가서 logs-*을(를) 선택합니다. 충돌이 log.offset에만 관련된 경우 더 이상 충돌 목록이 표시되지 않습니다. 다른 충돌이 있었던 경우 원래 백킹 인덱스는 충돌 목록에서 사라지고 대신 새 백킹 인덱스가 long 섹션에 표시됩니다.

Discover log.offset 필드에 적절한 아이콘이 표시되는지 확인할 수도 있습니다.

매핑 충돌이 있는 모든 백킹 인덱스에 대해 위의 단계를 반복하여 모든 충돌이 성공적으로 해결될 때까지 진행합니다.

참고 자료:

• ECS 필드 참조
• 문서 재색인

결론

이 블로그의 단계를 따르면 매핑 충돌을 해결하고 모든 새 데이터가 올바르게 매핑되는지 확인할 수 있습니다. 이는 필요한 구성 요소 템플릿을 데이터 소스에 연결함으로써 달성할 수 있습니다. 이 워크플로우는 즉각적인 문제를 해결할 뿐만 아니라 데이터와 요구 사항이 진화함에 따라 스키마 변경을 관리할 수 있는 안전하고 반복 가능한 프로세스를 구축합니다.