Elasticsearch 데이터 소스 문제 해결

Elasticsearch 데이터 소스 문제 해결

이 문서는 Grafana에서 Elasticsearch 데이터 소스를 사용할 때 겪을 수 있는 일반적인 오류에 대한 문제 해결 정보를 제공해요. 연결, 인증, 클러스터 상태, 인덱스, 쿼리, 버전 오류 순으로 진단해 보세요.

출처: Troubleshoot issues with the Elasticsearch data source

본문

연결 오류

다음 오류는 Grafana가 Elasticsearch에 연결을 설정하거나 유지하지 못할 때 발생해요.

Elasticsearch에 연결 실패

오류 메시지: "Health check failed: Failed to connect to Elasticsearch"

원인: Grafana가 Elasticsearch 서버에 네트워크 연결을 설정할 수 없음.

해결책:

1. 데이터 소스 구성의 Elasticsearch URL이 올바른지 확인해요.
2. Elasticsearch가 실행 중이고 Grafana 서버에서 접근 가능한지 확인해요.
3. 연결을 차단하는 방화벽 규칙이 없는지 확인해요.
4. 프록시를 사용한다면 프록시 설정이 올바른지 확인해요.
5. Grafana Cloud라면 Elasticsearch 인스턴스가 공개적으로 접근 불가한 경우 Private data source connect를 구성했는지 확인해요.

Request timed out

오류 메시지: "Health check failed: Elasticsearch data source is not healthy. Request timed out"

원인: 응답을 받기 전에 Elasticsearch 연결이 타임아웃됨.

해결책:

1. Grafana와 Elasticsearch 사이의 네트워크 지연을 확인해요.
2. Elasticsearch가 과부하되거나 성능 문제를 겪지 않는지 확인해요.
3. 필요하면 데이터 소스 구성의 타임아웃 설정을 늘려요.
4. 네트워크 장치(로드 밸런서, 프록시)가 연결을 타임아웃시키는지 확인해요.

데이터 소스 URL 파싱 실패

오류 메시지: "Failed to parse data source URL"

원인: 데이터 소스 구성에 입력된 URL이 유효하지 않음.

해결책:

1. URL 형식이 올바른지 확인해요(예: http://localhost:9200 또는 https://elasticsearch.example.com:9200).
2. URL에 프로토콜(http:// 또는 https://)이 포함됐는지 확인해요.
3. URL에서 후행 슬래시나 유효하지 않은 문자를 제거해요.

인증 오류

다음 오류는 인증 자격 증명 또는 권한에 문제가 있을 때 발생해요.

Unauthorized (401)

오류 메시지: "Health check failed: Elasticsearch data source is not healthy. Status: 401 Unauthorized"

원인: 인증 자격 증명이 유효하지 않거나 없음.

해결책:

1. 사용자 이름과 비밀번호가 올바른지 확인해요.
2. API 키를 사용한다면 키가 유효하고 만료되지 않았는지 확인해요.
3. 선택한 인증 방법이 Elasticsearch 구성과 일치하는지 확인해요.
4. 사용자가 Elasticsearch 클러스터에 접근하는 데 필요한 권한을 갖고 있는지 확인해요.

Forbidden (403)

오류 메시지: "Health check failed: Elasticsearch data source is not healthy. Status: 403 Forbidden"

원인: 인증된 사용자가 요청한 리소스에 접근할 권한이 없음.

해결책:

1. 사용자가 지정된 인덱스에 읽기 권한이 있는지 확인해요.
2. Elasticsearch 보안 설정과 역할 매핑을 확인해요.
3. 사용자가 _cluster/health 엔드포인트에 접근할 권한이 있는지 확인해요.
4. AWS 호스팅 Elasticsearch 호환 도메인과 SigV4 인증을 사용한다면 IAM 정책이 필요한 권한을 부여하는지 확인해요.

클러스터 상태 오류

다음 오류는 Elasticsearch 클러스터가 비정상이거나 사용 불가할 때 발생해요.

클러스터 상태가 red

오류 메시지: "Health check failed: Elasticsearch data source is not healthy"

원인: Elasticsearch 클러스터 상태가 red이며, 하나 이상의 기본 샤드가 할당되지 않았음을 나타냄.

해결책:

1. GET /_cluster/health로 Elasticsearch 클러스터 상태를 확인해요.
2. 오류가 있는지 Elasticsearch 로그를 검토해요.
3. 클러스터의 모든 노드가 실행 중이고 연결되어 있는지 확인해요.
4. GET /_cat/shards?v&h=index,shard,prirep,state,unassigned.reason로 할당되지 않은 샤드를 확인해요.
5. 클러스터 리소스를 늘리거나 샤드 수를 줄이는 것을 고려해요.

Bad Gateway (502)

오류 메시지: "Health check failed: Elasticsearch data source is not healthy. Status: 502 Bad Gateway"

원인: Grafana와 Elasticsearch 사이의 프록시 또는 로드 밸런서가 오류를 반환함.

해결책:

1. 연결 경로의 프록시나 로드 밸런서의 상태를 확인해요.
2. Elasticsearch가 실행 중이고 연결을 수락하는지 확인해요.
3. 자세한 내용은 프록시/로드 밸런서 로그를 검토해요.
4. 프록시 타임아웃이 Elasticsearch 요청에 적절하게 구성됐는지 확인해요.

인덱스 오류

다음 오류는 구성된 인덱스 또는 인덱스 패턴에 문제가 있을 때 발생해요.

인덱스를 찾을 수 없음

오류 메시지: "Error validating index: index_not_found"

원인: 지정된 인덱스 또는 인덱스 패턴이 기존 인덱스와 일치하지 않음.

해결책:

1. 데이터 소스 구성의 인덱스 이름 또는 패턴을 확인해요.
2. GET /_cat/indices로 인덱스가 존재하는지 확인해요.
3. 시간 기반 인덱스 패턴(예: [logs-]YYYY.MM.DD)을 사용한다면 선택한 시간 범위에 대한 인덱스가 존재하는지 확인해요.
4. 사용자가 인덱스에 접근할 권한이 있는지 확인해요.

시간 필드를 찾을 수 없음

오류 메시지: "Could not find time field '@timestamp' with type date in index"

원인: 지정된 시간 필드가 인덱스에 없거나 date 유형이 아님.

해결책:

1. 데이터 소스 구성의 시간 필드 이름이 인덱스의 필드와 일치하는지 확인해요.
2. GET /<index>/_mapping으로 필드 매핑을 확인해요.
3. 시간 필드가 text나 keyword가 아닌 date 유형으로 매핑됐는지 확인해요.
4. 필드 이름이 다르면(예: @timestamp 대신 timestamp) 데이터 소스 구성을 업데이트해요.

쿼리 오류

다음 오류는 쿼리 문법 또는 구성에 문제가 있을 때 발생해요.

버킷이 너무 많음

오류 메시지: "Trying to create too many buckets. Must be less than or equal to: [65536]."

원인: 쿼리가 Elasticsearch가 허용하는 것보다 더 많은 집계 버킷을 생성함.

해결책:

1. 쿼리의 시간 범위를 줄여요.
2. 날짜 히스토그램 간격을 늘려요(예: 10s에서 1m으로). Interval이 Auto로 설정된 중첩 집계에서 최신 플러그인 버전은 쿼리가 max_buckets를 초과할 때 자동 간격을 넓혀요.
3. 집계되는 문서 수를 줄이는 필터를 추가해요.
4. Elasticsearch의 search.max_buckets 설정을 늘려요(클러스터 관리자 접근 필요).
5. 이전 버전이라면 Elasticsearch 플러그인을 업데이트해요. 플러그인 업데이트 참고.

필수 필드 누락

오류 메시지: "Required one of fields [field, script], but none were specified."

원인: 필드를 지정하지 않고 지표 집계(예: Average, Sum, Min)를 추가함.

해결책:

1. 쿼리 편집기에서 지표 집계의 필드를 선택해요.
2. 선택한 필드가 인덱스에 존재하고 숫자 데이터를 담고 있는지 확인해요.

지원되지 않는 간격

오류 메시지: "unsupported interval ''"

원인: 인덱스 패턴에 지정된 간격이 유효하지 않음.

해결책:

1. 지원되는 간격을 사용해요: Hourly, Daily, Weekly, Monthly, Yearly.
2. 시간 기반 인덱스 패턴이 필요 없다면 No pattern을 사용하고 정확한 인덱스 이름을 지정해요.

버전 오류

다음 오류는 Elasticsearch 버전 호환성 문제가 있을 때 발생해요.

지원되지 않는 Elasticsearch 버전

오류 메시지: "Support for Elasticsearch versions after their end-of-life (currently versions < 7.17) was removed. Using unsupported version of Elasticsearch may lead to unexpected and incorrect results."

원인: Elasticsearch 버전이 Grafana 데이터 소스에서 더 이상 지원되지 않음.

해결책:

1. Elasticsearch를 지원 버전(7.17+, 8.x, 9.x)으로 업그레이드해요.
2. 버전 지원 정보는 Elastic Product End of Life Dates를 참고해요.
3. 쿼리는 여전히 동작할 수 있지만 Grafana는 지원되지 않는 버전의 기능을 보장하지 않아요.

Elastic Cloud Serverless 상태 확인이 410 Gone 반환

오류 메시지: Elastic Cloud Serverless에 연결할 때 상태 확인이 410 Gone 상태로 실패.

원인: 이전 버전의 Elasticsearch 플러그인이 Elastic Cloud Serverless가 더 이상 수락하지 않는 상태 확인 요청을 사용함.

해결책:

1. Elasticsearch 플러그인을 12.8.0 이상으로 업데이트해요. 플러그인 업데이트 참고.
2. preinstall_auto_update가 활성화되어 Grafana가 재시작 시 최신 플러그인을 설치하는지 확인하거나, Plugins and data > Plugins에서 수동으로 업데이트해요.
3. 플러그인 업데이트 후 Save & test를 다시 클릭해요.

기타 일반적인 문제

다음 문제는 특정 오류 메시지를 생성하지 않지만 흔히 발생해요.

빈 쿼리 결과

원인: 쿼리가 데이터를 반환하지 않음.

해결책:

1. 시간 범위에 인덱스의 데이터가 포함되는지 확인해요.
2. Lucene 쿼리 문법에 오류가 있는지 확인해요.
3. _search API로 Elasticsearch에서 쿼리를 직접 테스트해요.
4. 인덱스가 쿼리 필터와 일치하는 문서를 담고 있는지 확인해요.

느린 쿼리 성능

원인: 쿼리 실행에 오랜 시간이 걸림.

해결책:

1. 쿼리의 시간 범위를 줄여요.
2. 스캔되는 데이터를 제한하는 더 구체적인 필터를 추가해요.
3. 날짜 히스토그램 간격을 늘려요.
4. Elasticsearch 클러스터 성능과 리소스 사용률을 확인해요.
5. 더 나은 쿼리 라우팅을 위해 인덱스 별칭이나 데이터 스트림 사용을 고려해요.

브라우저 접근 모드 비활성화

오류 메시지: 직접 브라우저 접근을 더 이상 사용할 수 없거나, 브라우저 접근으로 구성된 데이터 소스가 실패함.

원인: Grafana 9.2.0에서 브라우저 접근 모드가 제거됨. Elasticsearch 데이터 소스는 Server(프록시) 접근을 사용해야 Grafana 백엔드가 Elasticsearch에 연결해요.

해결책:

1. Grafana에서 데이터 소스 구성을 열어요.
2. 접근 모드가 Server(프록시)로 설정되어 있는지 확인해요. 프로비저닝된 데이터 소스는 access: proxy를 사용해야 해요.
3. Save & test를 클릭해 연결을 확인해요.
4. 여전히 브라우저 CORS 오류가 보이면 Grafana와 Elasticsearch 플러그인을 업그레이드해요. 브라우저에서 Elasticsearch로 직접 요청을 시도한 이전 구성은 더 이상 지원되지 않아요.

추가 도움말

이 문제 해결 가이드를 따른 후에도 문제가 계속되면:

1. API별 지침은 Elasticsearch 문서를 확인해요.
2. Grafana 커뮤니티 포럼에서 유사한 이슈를 검토해요.
3. Enterprise 라이선스가 있다면 Grafana Support에 문의해요.

더 알아보기 (Learn more)

• Configure the Elasticsearch data source - 데이터 소스 구성
• Elasticsearch query editor - 쿼리 편집기
• Elasticsearch data source overview - 데이터 소스 개요
• Elasticsearch documentation - Elasticsearch 공식 문서
• Troubleshoot issues with the Elasticsearch data source - 원문 문서