문제 해결

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

알려진 문제

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

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

로그 애널리틱스 문제 해결

이 섹션에서는 로그 애널리틱스를 사용하여 트레이스 데이터를 쿼리할 때 표시될 수 있는 실패를 해결하는 방법을 설명합니다.

뷰가 존재하지 않는다는 오류 메시지

로그 애널리틱스 페이지의 쿼리 창에 SQL 쿼리를 입력하지만 SQL 파서에 다음 오류가 표시됩니다.

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views/OBS_VIEW_ID does not exist

FROM 문에 지정된 뷰를 찾을 수 없는 경우 이전 오류가 보고됩니다.

이 오류를 해결하려면 뷰에 적절한 문법이 있는지 확인합니다.

  • 보기의 정규화된 이름이 로그 애널리틱스 이름 지정 스키마에 필요한 문법을 따르는지 확인합니다. 기본 쿼리를 표시하여 뷰에 필요한 문법을 찾을 수 있습니다.

  • Google Cloud 프로젝트 ID, 위치, 버킷 ID, 데이터 세트 ID 또는 뷰 ID에 마침표(.)가 포함된 경우 필드가 작은따옴표(`)로 래핑되는지 확인합니다.

    예를 들어 Google Cloud 프로젝트의 ID가 example.com:bluebird이면 FROM 문은 다음과 같습니다.

    FROM `example.com:bluebird`.`us`.`_Trace`.`Spans`.`_AllSpans`

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

Google Cloud 프로젝트로 추적 데이터를 전송하는 애플리케이션이 있습니다. 하지만 Trace 탐색기 페이지를 열면 데이터가 표시되지 않습니다.

트레이스 데이터를 볼 수 없는 데는 다음과 같은 몇 가지 이유가 있을 수 있습니다.

  • 데이터를 보는 데 필요한 권한이 부여되지 않았습니다.
  • 추적 스팬이 프로젝트로 전송되지 않았습니다.
  • 애플리케이션에 트레이스 데이터를 쓰는 데 필요한 권한이 없습니다.
  • 추적 범위가 저장되지 않습니다.

다음 하위 섹션에서는 나열된 실패 시나리오를 문제 해결하는 방법을 설명합니다.

추적 데이터를 볼 권한이 있는지 확인

trace 데이터를 보려면 Cloud Trace 사용자 역할 (roles/cloudtrace.user)이 부여되어 있는지 확인하세요.

추적 스팬이 프로젝트로 전송되는지 확인

스팬이 프로젝트로 전송되고 있는지 확인하려면 다음 단계를 따르세요.

  1. Enable the Cloud Trace and Telemetry APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    두 API 모두 추적 스팬을 수집할 수 있습니다. 하지만 Telemetry API는 OpenTelemetry 생태계와 호환되고 Cloud Trace API보다 한도가 더 관대하므로 Telemetry API를 사용하는 것이 좋습니다.

  2. 사용 설정된 API 및 서비스 페이지로 이동하여 Cloud Trace API 및 Telemetry API 행을 찾습니다.

    이 두 API의 요청 수가 0이면 프로젝트로 전송된 trace 데이터가 없다는 것입니다.

애플리케이션에 추적 스팬을 작성하는 데 필요한 권한이 있는지 확인합니다.

애플리케이션에 프로젝트에 trace 데이터를 쓸 권한이 있는지 확인하려면 다음을 실행하세요.

  1. 사용 설정된 API 및 서비스 페이지로 이동하여 Cloud Trace API 및 Telemetry API 행을 찾고 오류 열을 검사합니다.

  2. 두 API 중 하나의 오류 열에 0이 아닌 값이 표시되면 해당 API를 통해 추적 데이터를 읽거나 쓰는 데 오류가 있는 것입니다. 오류 유형을 확인하려면 API를 선택하고 측정항목 탭을 선택한 후 API 메서드별 오류를 확인합니다.

    쓰기가 실패하면 사용자 인증 정보를 제공하는 서비스 계정에 다음 역할을 부여합니다.

트레이스 데이터가 저장되었는지 확인

Trace 스팬은 _Trace라는 관측 가능성 버킷에 저장됩니다. 이 버킷은 Google Cloud 프로젝트가 추적 스팬을 수신할 때 자동으로 프로비저닝됩니다. 하지만 프로비저닝이 실패하는 시나리오가 몇 가지 있습니다.

trace 데이터에 대한 관측 가능성 버킷이 있는지 확인하려면 [관측 가능성 버킷을 나열][trace-storage-list-buckets] 하거나 Trace 탐색기 페이지를 열면 됩니다. 예를 들어 다음과 같은 작업이 가능합니다.

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

    Trace 탐색기로 이동

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

  2. 다음과 유사한 배너가 표시되면 추적 데이터 스토리지가 프로비저닝되지 않은 것입니다.

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

    추적 데이터의 관측 가능성 버킷을 프로비저닝하려면 배너로 이동하여 사용 설정을 클릭합니다.

    사용 설정을 클릭하면 스팬이 프로젝트로 전송됩니다. 시스템이 스팬을 수신하면 _Trace라는 관측 가능성 버킷을 만드는 명령어를 실행합니다. 이 프로세스를 완료하는 데 몇 분 정도 걸릴 수 있습니다.

    초기화가 완료되면 알림 배너가 표시되고 Cloud Trace는 지난 한 시간 동안 전송된 모든 추적 데이터를 수집합니다. 이 데이터는 임시 버퍼에 저장되었습니다. 데이터가 Trace Explorer에 표시되기까지 몇 분 정도 걸릴 수 있습니다. 데이터가 표시되지 않으면 창을 새로고침합니다.

  3. 사용 설정 명령어가 실패하면 다음 메시지가 표시됩니다.

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

    실패를 해결하려면 티켓 제출을 클릭하여 Google Cloud 지원팀에 문의하세요.

특정 트레이스 검색 실패

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 프로젝트를 검색하지 않습니다.

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

  • 계측 문제가 있습니다. 예를 들어 추적의 일부 스팬만 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에서 스팬 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 컨텍스트 전파를 참조하세요.

로그 및 추적 데이터를 상호 연관시킬 수 없음

다음 중 하나를 수행하고 있습니다.

  • 트레이스 스팬을 보고 있으며 연결된 로그 항목을 확인하고 싶습니다. 하지만 로그 데이터가 나열되지 않거나 로그 탐색기 페이지를 열어도 로그 항목이 표시되지 않습니다.

  • 로그 항목을 보고 있으며 연결된 추적 스팬을 보고 싶습니다. 하지만 로그 항목의 옵션을 사용하여 Trace 탐색기 페이지를 열면 trace 데이터가 표시되지 않습니다.

이러한 오류를 해결하려면 모니터링 가능성 범위를 구성하세요. 이 범위는 해당 탐색기 페이지가 열릴 때 사용할 추적 범위와 로그 범위를 지정합니다. 자세한 내용은 다중 프로젝트 쿼리를 위한 관측 가능성 범위 구성을 참고하세요.

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

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

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

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