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 데이터를 Google Cloud 프로젝트로 전송하는 OTLP 내보내기 도구로 애플리케이션을 구성합니다.

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

  • 원격 분석 API 또는 Cloud Trace API를 직접 호출합니다.

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

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

계측 샘플

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

맞춤 스팬 만들기

OpenTelemetry 및 클라이언트 라이브러리를 사용하면 맞춤 스팬을 만들 수 있지만 이러한 라이브러리는 RPC 경계에서 스팬을 자동으로 생성하므로 수동으로 만들지 않아도 됩니다.

기존 스팬에 맞춤 주석과 태그를 추가하여 애플리케이션과 관련된 정보를 추가할 수도 있고, 자체 주석과 태그가 있는 새 하위 스팬을 만들어 더 세부적인 수준으로 애플리케이션의 동작을 추적할 수도 있습니다.

일반적으로 라이브러리는 추적 ID와 샘플링 상태를 비롯한 현재 스팬에 관한 정보를 보유하는 전역 추적 컨텍스트를 유지합니다. 애플리케이션은 전역 트레이스 컨텍스트를 통해 현재 스팬에 액세스할 수 있습니다. 컨텍스트는 전역이므로 정확한 추적 데이터를 유지하려면 다중 스레드 애플리케이션이 스레드 간에 컨텍스트를 전파해야 합니다.

강제 추적 샘플링

요청 경로의 각 구성요소가 독립적으로 샘플링을 결정하기 때문에 스팬이 샘플링되도록 강제할 수는 없습니다. 하지만 추적 헤더에서 sampled 플래그를 true로 설정하여 다운스트림 구성요소에 영향을 줄 수 있습니다. 이 설정은 요청을 샘플링하기 위한 하위 구성요소에 대한 힌트입니다. trace 헤더에 대한 자세한 내용은 컨텍스트 전파 프로토콜을 참조하세요.

  • 애플리케이션: 계측 로직이 sampled 플래그를 따르는 방식을 구성합니다. 예를 들어 OpenTelemetry를 사용하는 경우 ParentBased 샘플러를 사용하여 상위의 샘플링 플래그를 따르도록 할 수 있습니다.

  • Google Cloud 서비스: 각 서비스는 자체 추적 지원을 결정합니다. 일반적으로 서비스는 상위 샘플링 플래그를 힌트로 허용하면서 자체 샘플링 비율 제한을 적용합니다.

예시를 사용하여 측정항목과 trace 간의 상관관계 보기

실례를 사용하여 측정항목 데이터와 트레이스의 상관관계를 파악할 수 있습니다. 실례는 측정항목 측정과 연결된 대표적인 샘플 요청 또는 스팬입니다. 예를 들어 예시에는 trace에 대한 링크가 포함될 수 있으며, 이를 통해 측정항목과 trace 데이터의 상관관계를 파악할 수 있습니다. OpenTelemetry 기반 예시는 예시를 사용하여 측정항목과 trace 간의 상관관계 보기를 참고하세요.

추적 데이터의 SQL 쿼리 결과를 표시하는 대시보드 차트에 시스템 생성 예시가 표시될 수 있습니다. 이러한 예시는 특정 쿼리 결과를 트레이스에 직접 연결합니다. 자세한 내용은 트레이스 예시 생성 및 표시를 참고하세요.

프로젝트 및 플랫폼 구성

이 섹션에서는 필수 API와 ID 및 액세스 관리 (IAM) 역할을 설명하고 플랫폼의 인증 사용자 인증 정보를 구성하는 방법을 설명합니다.

API 사용 설정

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

아직 사용 설정되지 않은 API가 있으면 원격 분석 및 Cloud Trace API를 사용 설정합니다.

API 사용 설정에 필요한 역할

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

API 사용 설정

IAM 역할 부여

필요한 IAM 역할은 Google Cloud 콘솔에서 trace 데이터를 보는지 아니면 프로젝트에 trace 데이터를 작성하는지에 따라 다릅니다.

  • Google Cloud 콘솔을 사용하여 trace 데이터를 보는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Cloud Trace 사용자 (roles/cloudtrace.user) IAM 역할을 부여해 달라고 요청하세요.

  • Cloud Trace API를 사용하여 trace 데이터를 작성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Cloud Trace 에이전트 (roles/cloudtrace.agent) IAM 역할을 부여해 달라고 요청하세요.

  • 원격 분석 API를 사용하여 추적 데이터를 작성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Cloud 원격 분석 작성자 역할 (roles/telemetry.writer) IAM 역할을 부여해 달라고 요청하세요.

인증

이 섹션에서는 애플리케이션이Google Cloud 에서 실행될 때와 다른 곳에서 실행될 때 인증하는 방법을 설명합니다.

Google Cloud에서 실행

애플리케이션이 Google Cloud에서 실행되는 경우 일반적으로 사용자 인증 정보를 제공할 필요가 없습니다. 하지만 일부 언어 클라이언트 라이브러리는 Google Cloud에서 호스팅되는 경우에도 프로젝트 ID가 필요합니다.

Google Cloud 플랫폼에 Cloud Trace API 액세스 범위가 사용 설정되어 있는지 확인합니다. 다음 구성에서는 기본 액세스 범위 설정에 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"

다음 단계