문제 해결

이 페이지에는 Trace의 문제 해결 정보가 포함되어 있습니다.

알려진 문제

이 섹션에는 알려진 문제가 나열되어 있습니다.

  • Telemetry API를 사용하여 Google Cloud 프로젝트에 작성된 스팬은 Cloud Trace API에서 액세스할 수 없습니다. 예를 들어 이러한 트레이스를 나열하려고 하면 명령어가 404 Not Found 오류와 함께 실패합니다.

Trace 탐색기 페이지 문제 해결

이 섹션에서는 Trace Explorer 페이지를 사용할 때 문제를 해결하는 방법을 설명합니다.

Trace 탐색기 페이지에 데이터가 없음

Trace 탐색기 페이지를 사용하고 있으며 trace 데이터가 있을 것으로 예상될 때 Google Cloud 프로젝트에서 trace를 볼 수 없습니다.

다음 단계를 시도해 보세요.

  1. Cloud Trace API가 사용 설정되어 있고 데이터가 프로젝트에 기록되고 있는지 확인합니다.

    1. Google Cloud 콘솔에서 사용 설정된 API 및 서비스 페이지로 이동합니다.

      사용 설정된 API 및 서비스로 이동

    2. Cloud Trace API가 나열되면 다음 단계로 진행합니다. 그렇지 않으면 API를 사용 설정합니다.

      API를 사용 설정하려면 API 및 서비스 사용 설정을 클릭하고 'Cloud Trace API'를 검색한 후 옵션을 선택하고 사용 설정을 클릭합니다.

  2. 사용 설정된 API 및 서비스 페이지에서 Cloud Trace API 라벨이 지정된 행을 찾습니다.

  3. 오류 라벨이 지정된 열에 0이 아닌 값이 나열되면 Cloud Trace API를 통해 추적 데이터를 읽거나 쓰는 데 오류가 있는 것입니다. 오류의 원인에 관한 자세한 정보를 확인하려면 Cloud Trace API를 선택하고 측정항목 탭을 선택한 후 API 메서드별 오류 라벨이 지정된 차트를 찾습니다.

    • 쓰기가 실패하면 사용자 인증 정보를 제공하는 서비스 계정에 Cloud Trace 에이전트 역할 (roles/cloudtrace.agent)을 부여합니다. 이 역할에는 애플리케이션이 Google Cloud 프로젝트에 스팬 데이터를 쓸 수 있도록 하는 cloudtrace.traces.patch 권한이 포함되어 있습니다.

      자세한 내용은 Cloud Trace IAM 역할을 참조하세요.

    • 읽기에 실패하는 경우 Google Cloud 프로젝트의 IAM 역할에 Cloud Trace 사용자 역할 (roles/cloutrace.user)의 권한이 포함되어 있는지 확인합니다. 이 역할의 권한 목록은 Cloud Trace IAM 역할을 참고하세요.

  4. 요청 열에는 Cloud Trace API로 전송된 요청 수가 표시됩니다. 이 열이 0이면 해당 API를 통해 전송되는 추적 데이터가 없습니다.

    App Engine, Cloud Run, Cloud Run Functions는 Cloud Trace API를 사용하지 않고 추적 데이터를 전송합니다. 이러한 서비스만 사용하는 경우 다음 단계로 이동합니다.

    Cloud Trace API를 통해 trace 데이터를 전송하는 애플리케이션이 있고 요청 열이 0인 경우 애플리케이션과 프록시가 올바른 프로젝트로 trace를 보내도록 구성되었는지 확인합니다.

  5. Trace 탐색기 페이지에서 Trace 스토리지가 초기화되었는지 확인합니다.

    1. Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.

      Trace 탐색기로 이동

      검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

    2. 추적 저장소가 초기화되지 않으면 Trace 탐색기 페이지에 다음 텍스트가 포함된 배너가 표시됩니다.

      Trace storage is not initialized in this project. Enable trace storage to begin collecting trace data.

      추적 저장소를 초기화하려면 배너에서 사용 설정을 클릭합니다. 초기화는 일반적으로 몇 분 이내에 완료됩니다.

      초기화에 성공하면 알림 배너가 표시됩니다. 추적은 이전에는 버퍼에 저장되었던 지난 1시간 동안 전송된 추적 데이터를 수집합니다. 데이터가 Trace 탐색기에 표시되기 시작하면 몇 분 후에 새로고침할 수 있습니다.

      초기화가 실패했음을 나타내는 오류 메시지가 표시되면 Google Cloud 지원팀 구성원이 문제를 수동으로 해결해야 합니다. 티켓 제출을 클릭하여 이 절차를 시작합니다.

  6. Trace 탐색기 페이지에서 현재 프로젝트의 trace 데이터를 검색하는지 확인합니다. 툴바에서 범위 요소로 이동하여 범위 상세검색 메뉴를 펼치고 현재 프로젝트를 선택한 다음 적용을 선택합니다.

특정 트레이스 검색 실패

Trace 탐색기 페이지에 trace ID를 입력합니다. 트레이스를 찾을 수 없으며 다음과 유사한 메시지가 표시됩니다.

The select trace with ID abcde does not exist or is older than 30 days and has been deleted per our retention policy.

이 문제를 해결하려면 다음을 시도해 보세요.

  1. 추적 ID와 연결된 타임스탬프가 보관 기간 내에 있는지 확인합니다.

  2. 트레이스를 저장하는 Google Cloud 프로젝트를 확인하고 Google Cloud 콘솔의 리소스 선택기에서 이 프로젝트를 선택했는지 확인합니다. 기본적으로 Trace 탐색기 페이지는 선택한 프로젝트에 저장된 trace 데이터에만 액세스할 수 있습니다.

Trace 탐색기 페이지에 이전 데이터가 누락됨

Trace 탐색기 페이지를 사용하고 있으며 최근 데이터를 볼 수 있지만 기간 선택기를 30일 또는 더 큰 값으로 설정하면 이전 데이터가 표시되지 않습니다.

Trace 탐색기 페이지에는 Cloud Trace의 데이터 보관 기간인 30일을 초과하는 기간의 데이터가 표시되지 않습니다.

기간 선택기가 30일 이하인 경우 누락된 데이터는 Trace 탐색기 페이지에서 쿼리한 데이터베이스가 기간 설정보다 최근에 생성되었음을 나타냅니다. 예를 들어 이 값을 20일로 설정했는데 최근 10일의 데이터만 표시된다면 데이터베이스가 10일 전에 생성된 것입니다. 또한 이 데이터베이스에는 데이터베이스가 생성된 후 Google Cloud 프로젝트로 전송된 트레이스만 포함됩니다.

트레이스에 스팬이 누락됨

Trace 탐색기 페이지를 열고 볼 스팬을 선택합니다. 세부정보 플라이아웃에 트레이스가 표시되지만 일부 스팬이 누락되었습니다.

다음과 같은 이유로 스팬이 누락될 수 있습니다.

  • Trace 탐색기 페이지에서 trace의 스팬 데이터를 저장하는 모든 Google Cloud 프로젝트를 검색하지 않습니다.

  • 트레이스의 스팬 데이터를 저장하는 Google Cloud 프로젝트의 IAM 역할에 트레이스 데이터를 보는 데 필요한 권한이 포함되어 있지 않습니다.

  • 계측 문제가 있습니다. 예를 들어 추적의 일부 스팬만 Google Cloud 프로젝트로 전송되었습니다.

이 문제를 해결하려면 다음 단계를 따르세요.

  1. Trace 탐색기 페이지에서 범위 요소를 선택한 trace의 스팬을 저장하는 프로젝트를 나열하는 trace 범위로 설정해야 합니다.

    이전 단계에서 식별한 프로젝트를 포함하는 추적 범위가 없으면 기존 추적 범위를 만들거나 수정합니다. 자세한 내용은 trace 범위 만들기 및 관리를 참조하세요.

  2. 스팬 데이터를 저장하는 프로젝트에 Cloud Trace 사용자 역할 (roles/cloudtrace.user)이 있는지 확인합니다.

추적 데이터를 볼 권한이 없습니다.

Trace 탐색기 페이지를 보고 있는데 다음 알림이 표시됩니다.

You don't have the required permissions to view trace data for one or more projects listed in the trace scope.

이 메시지를 해결하려면 툴바에서 다음 단계를 따르세요.

  1. 범위 요소를 펼치고 선택된 추적 범위를 확인합니다.
  2. 범위 상세검색 플라이아웃에서 범위 관리를 선택합니다.
  3. 첫 번째 단계에서 식별한 추적 범위를 찾은 다음 세부정보를 펼쳐 Google Cloud 프로젝트 목록을 확인합니다.
  4. trace 범위의 각 Google Cloud 프로젝트에 대해 Cloud Trace 사용자 (roles/cloudtrace.user) 역할이 있는지 확인합니다. 프로젝트에 이 역할이 없는 경우 관리자 또는 프로젝트 소유자에게 이 역할을 부여해 달라고 요청하세요.

트레이스 스토리지 초기화 실패

Trace Explorer에 표시된 배너에서 사용 설정을 클릭하여 추적 저장소를 초기화하려고 하면 다음 오류가 표시됩니다.

Initializing trace storage has failed for an unexpected reason. Please file a support ticket for assistance.

스토리지 초기화에 실패하면 Google Cloud 지원팀 구성원이 문제를 수동으로 해결해야 합니다. 지원을 받으려면 티켓 제출을 클릭하세요.

trace에서 스팬 ID 메시지 누락

trace에 '누락된 스팬 ID' 메시지가 포함되어 있습니다.

분산 추적 시스템에서는 불완전한 trace가 예상됩니다. 샘플링된 스팬에 수신되지 않은 다른 스팬에 대한 참조가 포함되면 trace가 불완전합니다. 다음과 같은 이유로 해결되지 않은 참조가 발생할 수 있습니다.

  • 참조된 스팬이 샘플링되지 않았습니다.
  • 참조된 스팬이 샘플링되었지만 아직 Cloud Trace에서 수신되지 않았거나 스팬이 수신되었지만 저장되지 않았습니다.

불완전한 trace가 표시되면 Cloud Trace의 trace 세부정보 창에 '누락된 스팬 ID' 메시지가 표시됩니다.

'누락된 스팬 ID' 메시지가 계속 표시되면 다음을 시도해 보세요.

  • 관리하는 구성요소의 경우 이 필드가 있으면 헤더의 sampled 플래그를 준수하고 전파해야 합니다. 이 설정은 요청을 샘플링하기 위한 하위 구성요소에 대한 힌트입니다. trace 헤더에 대한 자세한 내용은 컨텍스트 전파 프로토콜을 참조하세요.

    Google Cloud 서비스는 일반적으로 이 힌트를 따릅니다. 하지만 trace 데이터를 쓰는 속도도 제한됩니다.

  • Cloud Service Mesh를 사용하는 경우 해당 구성의 trace 컨텍스트 전파 안내를 따라야 합니다. Cloud Service Mesh 안내는 Trace 컨텍스트 전파를 참조하세요.

OpenTelemetry를 사용하도록 Go 앱을 업데이트한 후 trace 데이터가 없음

애플리케이션에서 클라이언트 라이브러리를 사용하여 trace를 캡처하며 OpenTelemetry를 사용하도록 애플리케이션을 업데이트한 후에는 더 이상 Cloud Trace 데이터가 표시되지 않습니다.

일부 Go용 Cloud 클라이언트 라이브러리는 OpenCensus와 통합되었으므로 OpenCensus Bridge를 사용해야 합니다. 브리지에서 해결한 문제에 대한 자세한 내용은 OpenCensus Bridge를 참조하세요.

Go용 Cloud 클라이언트 라이브러리 업데이트에 대한 자세한 내용은 문제 #4237을 참고하세요.