Cloud Trace 계측

이 문서에서는 Cloud Trace용 애플리케이션 계측 방법을 간략하게 설명합니다. Cloud Trace 설정에 대한 자세한 안내는 언어별 설정 페이지를 참조하세요.

Cloud Trace에서는 애플리케이션의 분산 추적 데이터가 제공됩니다. 애플리케이션을 계측한 다음 단일 요청의 지연 시간 데이터를 검사하고 Cloud Trace 콘솔에서 전체 애플리케이션의 총 지연 시간을 볼 수 있습니다.

애플리케이션을 계측해야 하는 경우

성능 검증 또는 문제 해결을 위한 trace 데이터가 자동으로 캡처되지 않으면 애플리케이션을 계측합니다.

애플리케이션을 계측하여 성능을 파악하고 오류를 해결하는 데 도움이 되는 특정 정보를 수집합니다. 여러 오픈소스 계측 프레임워크는 로그, 측정항목, trace 데이터를 수집하고 를 포함한 모든 공급업체에 해당 데이터를 전송할 수 있습니다 Google Cloud. 에이전트 애플리케이션의 경우 일부 프레임워크는 프롬프트와 응답을 수집하거나 일부 원격 Google Cloud MCP 서버 호출을 추적할 수 있는 컨텍스트를 전달할 수 있습니다.

애플리케이션을 계측하려면 공급업체 및 제품별 API 또는 클라이언트 라이브러리 대신 OpenTelemetry와 같은 오픈소스인 공급업체 중립적인 계측 프레임워크를 사용하는 것이 좋습니다. 이러한 프레임워크에 대한 자세한 내용은 계측 및 모니터링 가능성 및 계측 방법 선택을 참조하세요.

애플리케이션 계측 방법

애플리케이션을 계측하는 데 사용할 수 있는 방법은 여러 가지가 있습니다.

  • 권장사항: OpenTelemetry를 사용하고, trace 데이터를 수집기로 전송하는 OTLP 내보내기 도구로 애플리케이션을 구성하고, Telemetry (OTLP) API를 사용하여 trace 데이터를 프로젝트로 전송하도록 수집기를 구성합니다. Google Cloud 권장사항에 대해 자세히 알아보려면 계측 방법 선택을 참조하세요.

  • OpenTelemetry를 사용하고 Telemetry API를 사용하여 trace 데이터를 프로젝트로 전송하는 OTLP 내보내기 도구로 애플리케이션을 구성합니다. Google Cloud

  • Compute Engine에서 실행되는 애플리케이션을 작성하는 경우 운영 에이전트 및 OpenTelemetry Protocol (OTLP) 수신기를 사용하여 애플리케이션에서 추적과 측정항목을 수집할 수 있습니다. 운영 에이전트는 로그를 수집할 수도 있지만 OTLP를 사용할 수는 없습니다. 자세한 내용은 운영 에이전트 및 OTLP 사용 및 운영 에이전트 개요를 참조하세요.

  • Telemetry API 또는 Cloud Trace API를 직접 호출합니다.

  • Cloud Trace 클라이언트 라이브러리 를 사용하거나 OpenTelemetry용 Cloud Trace 내보내기 도구를 사용합니다.

  • Spring Boot 애플리케이션의 경우 수집하는 trace 데이터를 Cloud Trace로 전달하도록 구성합니다. 이 절차에 대한 자세한 내용은 Spring Cloud for Google CloudCloud Trace를 참조하세요.

제공하는 계측 샘플은 OpenTelemetry를 사용합니다.

  • trace 생성을 지원하는 원격 Google Cloud MCP 서버와 이러한 서버에 스팬을 만들도록 애플리케이션을 구성하는 방법을 알아보려면 Trace를 사용하여 MCP 호출 조사를 참조하세요.

스팬을 만들어야 하는 경우

Cloud Trace 클라이언트 라이브러리는 일반적으로 trace ID와 trace 샘플링 여부 등 현재 스팬에 대한 정보가 있는 전역 trace 컨텍스트를 유지합니다. 이러한 라이브러리는 일반적으로 RPC 경계에 스팬을 만듭니다. 하지만 기본 생성 알고리즘이 요구사항을 충족하지 않으면 스팬을 만들어야 할 수 있습니다.

현재 활성 스팬은 전역 trace 컨텍스트에서 액세스할 수 있으며, 경우에 따라 추적자 객체로 래핑됩니다. 커스텀 주석과 태그를 기존 스팬에 사용하여 애플리케이션과 관련된 정보를 추가하거나, 자체 주석과 태그로 새 하위 스팬을 만들어 세밀하게 세분화된 애플리케이션의 동작을 추적할 수 있습니다. 컨텍스트는 전역적이므로 컨텍스트를 업데이트하는 다중 스레드 애플리케이션은 적절한 격리를 사용해야 합니다.

사용자 인증 정보를 제공해야 하는 경우

일반적으로 에서 실행하는 경우 애플리케이션에 사용자 인증 정보를 제공하거나 애플리케이션에서 Google Cloud project ID를 지정할 필요가 없습니다 Google Cloud. 일부 언어의 경우, 에서 실행하여도 Google Cloud 프로젝트 ID를 지정해야 합니다. Google Cloud또한 Google Kubernetes Engine에 Autopilot을 사용하거나 GKE용 워크로드 아이덴티티 제휴를 사용 설정하는 경우 GKE용 워크로드 아이덴티티 제휴를 사용하도록 애플리케이션을 구성해야 합니다.

외부에서 실행하는 경우 Google Cloud애플리케이션에 사용자 인증 정보를 제공해야 합니다. 또한 애플리케이션에서 프로젝트 ID를 지정해야 합니다.Google Cloud

자세한 내용은 언어별 설정 페이지를 참조하세요.

요청을 강제로 추적하는 방법

애플리케이션이 항상 모든 스팬을 샘플링하지 않는 한, 엔드 투 엔드 요청의 각 구성요소가 자체적으로 샘플링을 결정하기 때문에 요청이 엔드-투-엔드 trace되도록 강제하는 것은 일반적으로 가능하지 않습니다. 그러나 sampled 플래그(이 플래그를 true로 설정)를 trace 헤더에 추가하여 결정에 영향을 줄 수 있습니다. 이 설정은 요청을 샘플링하기 위한 하위 구성요소에 대한 힌트입니다. trace 헤더에 대한 자세한 내용은 컨텍스트 전파 프로토콜을 참조하세요.

코드를 소유한 다운스트림 구성요소의 경우 계측 로직이 sampled 플래그를 따를지 여부를 결정해야 합니다. 예를 들어 계측에 OpenTelemetry 를 사용하는 경우 ParentBased 샘플러 를 사용하여 상위 샘플링된 플래그를 따르도록 합니다.

Google Cloud Cloud Trace에 추적 정보를 기록하는서비스는 일반적으로 상위 샘플링 플래그를 힌트로 허용합니다. 그러나 대부분의 서비스도 샘플링을 비율 제한합니다. 각 Google Cloud 서비스 는 추적 지원 여부, 상위 샘플링 플래그 사용 방법, 샘플링 비율 제한을 결정합니다.

측정항목과 trace 데이터의 상관관계 분석 방법

측정항목 데이터 포인트에 예시를 연결하여 분포 값 측정항목 데이터와 trace의 상관관계를 분석할 수 있습니다. 필요한 구성 단계를 완료하면 권장되는 계측 라이브러리인 OpenTelemetry가 이러한 예시를 자동으로 추가합니다. 자세한 내용은 예시를 사용하여 측정항목과 trace 간의 상관관계 보기를 참조하세요.

프로젝트 및 플랫폼 구성

  1. Cloud Trace API가 사용 설정되어 있는지 확인합니다.

    기본적으로 Google Cloud 프로젝트에는 Cloud Trace API가 사용 설정되어 있으므로 별다른 조치를 취할 필요가 없습니다. 그러나 조직에서 정의한 보안 제약 조건으로 인해 API가 사용 중지되었을 수 있습니다. 문제 해결 정보는 제약 조건이 있는 Google Cloud 환경에서 애플리케이션 개발을 참조하세요.

    Cloud Trace API를 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한을 이미 보유하고 있을 가능성이 높습니다. 그렇지 않은 경우 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법을 알아보세요.

    API 사용 설정하기

  2. 플랫폼을 구성합니다.

    및 기타 플랫폼에서 Cloud Trace를 사용할 수 있습니다. Google Cloud

    • Google Cloud: 애플리케이션이 Google Cloud에서 실행되는 경우 클라이언트 라이브러리에 서비스 계정 형식으로 사용자 인증 정보를 제공할 필요가 없습니다. 하지만플랫폼에 Cloud Trace API 액세스 범위가 사용 설정되어 있는지 확인해야 합니다. Google Cloud

      다음 구성에서는 기본 액세스 범위 설정에 Cloud Trace API 액세스 범위가 포함됩니다.

      커스텀 액세스 범위를 사용하는 경우 Cloud Trace API 액세스 범위가 사용 설정되어 있는지 확인해야 합니다. 예를 들어 Google Cloud CLI를 사용하여 GKE 클러스터를 만들고 --scopes 플래그를 지정하면 범위에 trace.append가 포함되어 있는지 확인합니다. 다음 명령어는 --scopes 플래그의 설정 방법을 보여줍니다.

      gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

    • 로컬 및 기타 위치에서 실행: 애플리케이션이 외부에서 실행되는 경우 클라이언트 라이브러리에 사용자 인증 정보를 서비스 계정 형식으로 제공해야 합니다.Google Cloud 서비스 계정에 Cloud Trace 에이전트(roles/cloudtrace.agent) 역할이 부여되어야 합니다. 역할에 대한 자세한 내용은 IAM으로 액세스 제어를 참조하세요.

      클라이언트 라이브러리는Google Cloud 애플리케이션 기본 사용자 인증 정보 (ADC) 를 사용하여 애플리케이션의 사용자 인증 정보를 찾습니다. 세 가지 방법 중 하나로 이러한 사용자 인증 정보를 제공할 수 있습니다.

      • gcloud auth application-default login 실행

      • 운영체제의 기본 경로에 서비스 계정을 배치합니다. 다음은 Windows 및 Linux의 기본 경로를 보여줍니다.

        • Windows: %APPDATA%/gcloud/application_default_credentials.json

        • Linux: $HOME/.config/gcloud/application_default_credentials.json

      • GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 경로로 설정합니다.

        Linux/macOS

          export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

        Windows

          set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

        PowerShell:

          $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

다음 단계

GitHub 및 기타 오픈소스 저장소에 대한 자세한 구성 정보, 샘플, 링크를 보려면 언어별 설정 페이지로 이동하세요.