문제 해결

문제 해결 (Troubleshooting)

이 페이지는 Grafana Logs Drilldown을 시작하고 사용할 때 발생하는 일반적인 문제를 다뤄요. 메뉴에 보이지 않음, Loki 구성, 서비스·라벨·필드·패턴·쿼리 오류를 해결하는 방법을 설명해요.

출처: 문서

본문

이 페이지는 Grafana Logs Drilldown을 시작하고 사용할 때 발생하는 일반적인 문제를 다뤄요.

메뉴에서 Logs Drilldown이 보이지 않음 (Can't see Logs Drilldown in the menu)

Grafana Explore Logs는 Grafana v11.3.0부터 v11.5까지의 버전에 기본 설치돼요. Logs Drilldown은 Grafana v11.6.11 이상 버전에 기본 설치돼요. Grafana v12 이상에서 Drilldown 메뉴는 모든 Drilldown 앱을 기본 포함해요. 이 기능의 이름 변경에 대한 자세한 내용은 이 블로그 포스트를 참고해요.

두 이름 중 어느 것으로도 Logs Drilldown이 보이지 않으면 Logs Drilldown 플러그인이 설치·구성되어 있는지 확인하세요.

Note

Logs Drilldown 플러그인을 다운로드하려면 인스턴스에 인터넷 연결이 필요해요. 오프라인 환경에서 작업한다면 Logs Drilldown 플러그인을 별도로 다운로드해 Grafana의 /plugins 저장소에 추가할 수 있어요.

Grafana 관리자에게 확인해 보세요. 모든 Grafana Drilldown 앱은 Grafana에서 datasources:explore 권한을 요구해요.

Loki가 제대로 구성되었는지 확인 (Ensure Loki is properly configured)

Logs Drilldown을 사용하려면 Loki가 제대로 구성되어 있어야 해요. 전체 지침은 Access or install Grafana Logs Drilldown에서 찾을 수 있어요.

서비스 선택 오류 (Service selection errors)

이 섹션은 서비스 선택 페이지의 오류를 다뤄요.

서비스가 없음 (There are no services)

Logs Drilldown에 접근할 때 모든 것이 unknown_service로 표시된다면 다음 수정을 시도해 보세요:

  1. Loki에서 volume_enabled 구성 값을 설정해 Volume API를 활성화해요. Loki 3.1 이상에서 기본 활성화돼요.
  2. Loki에서 discover_service_name 구성 값을 설정해 서비스 식별에 사용할 라벨을 지정해요.

[라벨]에서 로그가 없음 (No logs found in [label])

이 메시지는 선택한 라벨이 현재 시간 범위에 로그 볼륨 데이터가 없을 때 나타나요. 다음 수정을 시도해 보세요:

  1. 이 라벨에 로그가 마지막으로 기록된 시점을 찾으려면 시간 범위를 넓혀요.
  2. 활성 로그 데이터가 있는 다른 라벨이나 서비스를 선택해요.
  3. 로그 수집 파이프라인을 확인해 이 라벨에 대한 로그가 수집되고 있는지 검증해요.

로그 볼륨이 구성되지 않음 (Log volume has not been configured)

이 오류는 Loki의 volume API가 활성화되지 않았음을 나타내는데, Logs Drilldown이 서비스 볼륨을 표시하는 데 필요해요. 이를 해결하려면 Loki 구성에서 volume을 활성화해요:

limits_config:
  volume_enabled: true

자세한 내용은 Loki 구성 문서를 참고해요.

이 메시지는 서비스 선택 페이지에서 서비스를 검색할 때 검색어와 일치하는 결과가 없을 때 나타나요. 다음 수정을 시도해 보세요:

  1. 검색어에 오타가 있는지 확인해요.
  2. 부분 일치 또는 다른 검색어를 시도해요.
  3. 검색을 지워 사용 가능한 모든 서비스를 봐요.

감지된 레벨이 없음 (There are no detected levels)

Logs Drilldown에서 detected_level 값이 보이지 않는다면 다음 수정을 시도해 보세요:

  1. Loki에서 discover_log_levels 구성 값을 설정해 레벨 감지를 활성화해요. Loki 3.1 이상에서 기본 활성화돼요.

라벨 및 필드 오류 (Label and field errors)

이 섹션은 Logs Drilldown의 라벨과 필드 관련 오류를 다뤄요.

라벨이 없음 (There are no labels)

Logs Drilldown에서 라벨이 보이지 않는다면 다음 수정을 시도해 보세요:

  1. 컬렉터가 라벨을 첨부하도록 제대로 구성되어 있는지 확인해요.

라벨에 대한 자세한 내용은 Loki labels 문서를 참고해요.

선택된 라벨 없음 (No labels selected)

이 메시지는 로그를 필터링할 라벨을 선택하지 않았을 때 나타나요. Logs Drilldown은 결과를 표시하려면 최소 하나의 라벨 필터가 필요해요. 해결하려면:

  1. 서비스 선택 페이지에서 서비스 또는 다른 기본 라벨을 선택해요.
  2. 모든 라벨을 제거했다면 Reset filters 버튼을 클릭해 기본 선택을 복원해요.

잘못된 라벨 선택 (Invalid labels selected)

이 오류는 라벨 필터가 잘못된 상태일 때 발생해요. 일반적으로 남은 모든 필터가 부정 일치(같지 않음, regex 불일치)를 사용할 때예요. 다음 수정을 시도해 보세요:

  1. 긍정(포함) 일치를 사용하는 라벨 필터가 하나 이상 있는지 확인해요.
  2. Reset filters 버튼을 클릭해 유효한 라벨 선택을 복원해요.
  3. 로그를 제외(exclude)하는 대신 포함(include)하는 새 라벨 필터를 추가해요.

현재 라벨을 사용할 수 없음 (The labels are not available at this moment)

이 경고는 Logs Drilldown이 일시적으로 Loki에서 라벨 정보를 가져올 수 없을 때 나타나요. 다음 수정을 시도해 보세요:

  1. 잠시 기다린 후 페이지를 새로고침해요.
  2. 다른 시간 범위를 선택해 보세요.
  3. Grafana의 데이터 소스 설정에서 Loki 데이터 소스 연결을 확인해요.

이 필터와 일치하는 라벨/필드 없음 (No labels/fields match these filters)

이 메시지는 현재 필터가 사용 가능한 라벨이나 필드와 일치하지 않을 때 나타나요. 다음 수정을 시도해 보세요:

  1. Clear filters 버튼으로 현재 필터를 지워요.
  2. 시간 범위를 넓혀요.
  3. 라벨 필터 값이 올바르고 로그 데이터에 존재하는지 확인해요.

주어진 시간 범위에서 필드를 찾지 못함 (We did not find any fields for the given time range)

이 메시지는 현재 선택과 시간 범위에 대해 감지된 필드(구조화된 메타데이터 또는 파싱된 필드)가 없음을 나타내요. 다음 수정을 시도해 보세요:

  1. 더 많은 로그 데이터를 포함하도록 시간 범위를 넓혀요.
  2. 로그에 구조화된 데이터(JSON, logfmt 또는 기타 파싱 가능한 형식)가 포함되어 있는지 확인해요.
  3. Loki 구성에서 allow_structured_metadata: true를 설정해 구조화된 메타데이터가 활성화되어 있는지 확인해요.

Default fields 탭이 나타나지 않음 (Default fields tab not appearing)

Logs Drilldown 플러그인 설정에 Default fields 탭이 나타나지 않거나 지원되지 않는 메시지가 표시되면 다음을 확인하세요:

  1. Grafana 12.4 이상을 실행 중인지 확인해요. Default fields는 이 최소 버전을 요구해요.
  2. Grafana 구성에서 kubernetesLogsDrilldown 기능 플래그가 활성화되어 있는지 확인해요.
  3. 조직에서 Org Admin 역할이 있는지 확인해요.

Default fields 구성에 대한 자세한 내용은 Configure Logs Drilldown을 참고해요.

색상 레벨이 없음 (There are no color levels)

로그 심각도 레벨의 색상 코딩은 Loki의 설정이에요. Loki 구성 파일에 discover_log_levels: true가 있어야 해요.

쿼리 및 결과 오류 (Query and results errors)

이 섹션은 로그를 쿼리할 때 발생할 수 있는 일반적인 오류 메시지를 다뤄요.

"No logs match your search. Please review your filters or try a different time range." 메시지가 보이면 현재 필터와 시간 범위의 조합이 결과를 반환하지 않는다는 뜻이에요. 다음 수정을 시도해 보세요:

  1. 더 큰 로그 창을 포함하도록 시간 범위를 넓혀요.
  2. 라벨 필터를 검토하고 너무 제한적인 필터를 제거해요.
  3. 라인 필터(검색 텍스트)에 오타나 너무 구체적인 패턴이 있는지 확인해요.
  4. 활성 패턴 필터(include 또는 exclude)가 있다면 지워서 로그가 나타나는지 봐요.

Tip

오류 메시지와 함께 나타나는 Clear filters 버튼을 클릭해 모든 필터를 리셋하고 새로 시작할 수 있어요.

잘못된 필터 파라미터로 인해 로그를 검색할 수 없음 (Logs could not be retrieved due to invalid filter parameters)

이 오류는 쿼리에 잘못된 문법이 있을 때 발생해요. 일반적으로 라인 필터의 잘못된 정규 표현식에서 비롯돼요. 다음 수정을 시도해 보세요:

  1. 라인 필터에 잘못된 regex 문법이 있는지 확인해요. Loki는 정규 표현식에 RE2 문법을 사용해요.
  2. (, ), [, ], {, }, ., *, +, ?, ^, $, |, \\ 같은 특수 문자를 사용한다면 올바르게 이스케이프했는지 확인해요.
  3. 리터럴 텍스트를 검색한다면 라인 필터에서 regex 모드를 꺼요.

처리가 너무 큰 응답 (The response is too large to process)

이 오류는 Loki가 단일 응답으로 처리할 수 있는 것보다 더 많은 데이터를 반환할 때 나타나요. 다음 수정을 시도해 보세요:

  1. 반환되는 데이터 양을 줄이도록 시간 범위를 좁혀요.
  2. 더 구체적인 라벨 필터를 추가해 더 작은 로그 부분집합을 대상으로 해요.
  3. 라인 필터를 사용해 특정 텍스트를 검색하면 응답 크기가 줄어요.
  4. 관리자라면 Loki 서버 구성에서 max_recv_msg_size를 조정하는 것을 고려해요.

쿼리당 최대 항목 한도 초과 (Max entries limit per query exceeded)

이 오류는 쿼리가 구성된 한도가 허용하는 것보다 더 많은 로그 라인을 반환하려 한다는 뜻이에요. Loki는 단일 쿼리에서 반환할 수 있는 로그 항목 수에 기본 한도가 있어요. 다음 수정을 시도해 보세요:

  1. Logs Drilldown 인터페이스의 Line limit 설정을 줄여요. 이 옵션은 Logs 탭의 라인 필터 옆에서 찾을 수 있어요.
  2. 더 적은 결과를 반환하도록 시간 범위를 좁혀요.
  3. 일치하는 로그 수를 줄이려면 더 구체적인 필터를 추가해요.
  4. 관리자로서 더 높은 한도가 필요하다면 Loki 구성에서 max_entries_limit_per_query를 조정해요.

최대 시리즈 한도 초과 (Max series limit exceeded)

필드 브레이크다운을 볼 때 "Max series limit exceeded"가 보이면 쿼리가 Loki가 허용하는 것보다 더 많은 고유 라벨 값 조합을 반환했다는 뜻이에요. 다음 수정을 시도해 보세요:

  1. 고유 시리즈 수를 줄이도록 시간 범위를 줄여요.
  2. 필드 브레이크다운을 보기 전에 결과를 좁힐 추가 필터를 추가해요.
  3. 브레이크다운할 고유 값이 더 적은 다른 필드를 선택해요.
  4. 관리자라면 Loki 구성에서 max_query_series 한도를 늘릴 수 있지만, 이것이 쿼리 성능에 영향을 줄 수 있다는 점을 알아두세요.

Tip

trace_id, request_id, 타임스탬프 같은 고카디널리티(많은 고유 값) 필드는 이 한도에 걸릴 가능성이 더 높아요. 고카디널리티 필드를 탐색하기 전에 다른 라벨로 먼저 필터링하는 것을 고려해요.

부분 결과 표시 (Showing partial results)

"[필드]에 대한 부분 결과를 표시 중"이 보이면 쿼리가 오류를 만났지만 일부 데이터는 반환할 수 있었다는 뜻이에요. 이것은 대규모 쿼리의 타임아웃 오류에서 흔히 발생해요. 다음 수정을 시도해 보세요:

  1. 쿼리를 더 빠르게 만들도록 시간 범위를 좁혀요.
  2. 처리되는 데이터 양을 줄일 필터를 더 추가해요.
  3. 타임아웃이 지속되면 관리자에게 연락해 Loki 쿼리 타임아웃 설정을 확인해요.

패턴 오류 (Pattern errors)

이 섹션은 Patterns 기능과 관련된 오류 메시지를 다뤄요.

패턴 일치가 없음 (There are no pattern matches)

패턴 일치가 구성되지 않았어요.

  1. Loki 구성에서 pattern_ingester.enabled=true를 설정해 패턴 추출을 활성화해요. 다른 필요한 구성 알아보기.
  2. Loki 구성 파일 내에서 volume_enabled=true를 설정해 volume 엔드포인트를 활성화해요.

Note

Patterns 기능은 멀티 테넌트 또는 크로스 스택 데이터 소스를 지원하지 않아요.

Patterns 탭 UI에 "An error occurred within the plugin." 메시지가 보이거나 HTTP 500 오류 메시지 multiple org IDs present를 받는다면 문제를 우회할 두 가지 옵션이 있어요:

  • 단일 스택 Loki 데이터 소스를 사용해 Patterns를 복원해요.
  • 멀티 테넌트 또는 크로스 스택 데이터 소스로 다른 Logs Drilldown 기능을 계속 사용하려면 로그 패턴을 비활성화해요. Administration > Plugins and data > Plugins > Grafana Logs Drilldown으로 이동해 Disable patterns 체크박스를 선택해요. 이렇게 하면 Patterns API 사용이 비활성화되고 UI에서 Patterns 탭이 숨겨져요.

패턴을 감지할 수 없음 (Sorry, we could not detect any patterns)

이 메시지는 Loki의 패턴 인제스터가 활성화되었지만 로그에서 패턴이 추출되지 않았을 때 나타나요. 드물지만 특정 로그 형식에서 발생할 수 있어요. 다음 수정을 시도해 보세요:

  1. 패턴은 들어오는 로그에서 지속적으로 추출되므로 나중에 다시 확인해요.
  2. 패턴 감지가 효과적으로 작동할 만큼 로그에 볼륨이 충분한지 확인해요.
  3. 문제가 지속되면 Grafana Labs 커뮤니티 Slack 채널에 문의하거나 GitHub에 이슈를 열어주세요.

패턴은 최근 3시간 데이터에만 사용 가능 (Patterns are only available for the most recent 3 hours of data)

Loki의 패턴은 임시적이며 가장 최근 3시간 동안만 저장돼요. 그리고 로깅이 진화함에 따라 패턴은 시간이 지나며 변할 수 있어요. 선택한 시간 범위가 완전히 3시간 이상 전이라면 패턴이 보이지 않을 거예요. 패턴을 보려면:

  1. 마지막 3시간의 일부를 포함하도록 시간 범위를 조정해요.
  2. 시간 선택기를 사용해 더 최근 시간 창을 선택해요.

이 패턴은 로그를 반환하지 않음 (This pattern returns no logs)

이 오류는 패턴의 샘플 로그를 볼 때 패턴 쿼리가 결과를 반환하지 못할 때 나타나요. 패턴이 이후에 만료되거나 삭제된 로그에서 감지되었을 때 발생할 수 있어요. 일반적으로 조치가 필요 없어요. 다른 패턴을 선택하거나 시간 범위를 조정해 보세요.

이 패턴이 반환한 로그가 현재 쿼리 필터와 일치하지 않음

이 경고는 선택한 패턴과 일치하는 로그를 제외하는 활성 필터가 있을 때 나타나요. 패턴은 전체 로그 데이터에 존재하지만, 현재 필터가 그 로그가 나타나지 못하게 해요. 다음 수정을 시도해 보세요:

  1. Clear filters 버튼을 클릭해 충돌하는 필터를 제거해요.
  2. 현재 라벨·라인 필터를 검토해 왜 이 패턴을 제외하는지 이해해요.
  3. 보려는 로그를 포함하도록 필터를 조정해요.

JSON 패널 문제 (JSON panel issues)

이 섹션은 JSON 시각화 패널에 특정된 문제를 다뤄요.

JSON 필터링은 Loki 3.5.0 필요 (JSON filtering requires Loki 3.5.0)

"JSON filtering requires Loki 3.5.0. This view will be read only until Loki is upgraded to 3.5.0"이 보이면 Loki 인스턴스가 JSON 필터링 기능을 지원하지 않는다는 뜻이에요. JSON 패널은 여전히 로그를 표시하지만 JSON 필드 값을 클릭해 필터링할 수는 없어요. 필터링을 활성화하려면:

  1. Loki 인스턴스를 3.5.0 이상으로 업그레이드해요.
  2. 또는 필터링이 모든 Loki 버전에서 작동하는 Logs 또는 Table 시각화로 전환해요.

JSON 필드 감지 없음 (No JSON fields detected)

이 메시지는 JSON 패널을 볼 때 표시되지만 로그 라인이 JSON 형식이 아닐 때 나타나요. 이것은 오류라기보다 정보성이에요. 로그가 JSON 형식이 아니라면:

  1. 더 나은 경험을 위해 Logs 또는 Table 보기로 전환해요.
  2. JSON 보기는 JSON 형식의 로그 라인에 최적화되어 있어 다른 형식을 올바르게 표시하지 못할 수 있어요.

무언가를 찾을 수 없음 (I cannot find something)

GitHub에 이슈를 열거나 비공개로 연락해 무엇이 작동하지 않는지 알려주세요.

긴급한 문제가 있다면 지원을 통해 연락하세요. Grafana Cloud 사용자는 여기에서 지원 티켓을 열 수 있어요.

더 알아보기 (Learn more)