자바 및 OpenTelemetry

이 페이지는 OpenTelemetry를 사용하여 자바 애플리케이션용 Cloud Trace 데이터를 수집하려는 애플리케이션 개발자를 위해 설계되었습니다. OpenTelemetry는 trace 및 측정항목 데이터를 수집하는 일련의 계측 라이브러리로, 여러 백엔드와 함께 작동합니다. OpenTelemetry 및 자바를 사용하여 trace를 수집하려면 이 페이지의 설명대로 다음을 수행합니다.

  • OpenTelemetry 패키지를 설치합니다.
  • Cloud Trace로 스팬을 내보내도록 애플리케이션을 구성합니다.
  • 플랫폼을 구성합니다.

출시 정보는 다음을 참조하세요.

자바용 OpenTelemetry에 대한 최신 세부정보 및 추가 문서와 예시는 OpenTelemetry를 참조하세요.

시작하기 전에

  • 자바 8 이상을 사용해야 합니다.
  • Google Cloud 프로젝트에 Cloud Trace API가 사용 설정되었는지 확인합니다.

    1. 다음 버튼을 클릭하거나 Google Cloud Console에서 API 및 서비스를 선택한 후 Cloud Trace API를 선택합니다.

      Trace API로 이동

    2. Cloud Trace API 페이지에서 사용 설정이라는 버튼이 표시되면 클릭합니다. 이 버튼이 표시되지 않으면 선택한 프로젝트에 Cloud Trace API가 사용 설정된 것입니다.

OpenTelemetry 패키지 설치

trace를 수집하려면 OpenTelemetry trace 및 OpenTelemetry용 Cloud Trace 내보내기 도구를 애플리케이션의 Maven 또는 Gradle 파일에 추가합니다.

  • 최근 게시된 OpenTelemetry 종속 항목 목록은 MavenGradle을 참조하세요.

  • 필요한 내보내기 도구 종속 항목은 다음 테이블을 참조하세요.

    Maven

    <dependency>
      <groupId>com.google.cloud.opentelemetry</groupId>
      <artifactId>exporter-trace</artifactId>
      <version>0.15.0</version>
    </dependency>
    

    이전 문은 내보내기 도구 버전을 지정합니다. 최신 내보내기 도구 출시 버전을 선택했는지 확인합니다.

    Gradle

    implementation 'com.google.cloud.opentelemetry:exporter-trace:0.15.0'
    

    이전 문은 내보내기 도구 버전을 지정합니다. 최신 내보내기 도구 출시 버전을 선택했는지 확인합니다.

Cloud Trace로 스팬 내보내기 구성

수집된 Trace 데이터를 내보내려면 TraceExporter 객체를 사용합니다. 다음은 기본 구성으로 이 객체를 만드는 방법을 보여줍니다.

TraceExporter traceExporter = TraceExporter.createWithDefaultConfiguration();

또한 구성을 지정한 후 이를 내보내기 도구로 전달할 수 있습니다. 예를 들어 다음 코드는 Google Cloud 프로젝트를 설정합니다.

TraceExporter traceExporter = TraceExporter.createWithConfiguration(
  TraceConfiguration.builder().setProjectId("MY_PROJECT").build());

내보내기 도구가 구성된 후 TracerProvider를 설정합니다.

OpenTelemetrySdk.builder()
          .setTracerProvider(
              SdkTracerProvider.builder()
                  .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                  .build())
          .buildAndRegisterGlobal();

이전 예시에서 BatchSpanProcessor를 호출하면 제공자가 백그라운드 프로세스로 스팬을 전송하도록 구성됩니다. Cloud Run을 사용하지 않는 경우 이 구성을 사용하는 것이 좋습니다. Cloud Run에서는 백그라운드 프로세스를 지원하지 않습니다.

인증 필드 설정 방법에 대한 자세한 내용은 OpenTelemetry에 대한 Cloud Trace 내보내기 도구의 설정 섹션을 참조하세요.

스팬 만들기

trace 스팬 캡처를 위해 애플리케이션을 구성하는 방법은 OpenTelemetry Trace를 참조하세요. 이 페이지에서는 다음 모든 작업의 수행 방법을 설명합니다.

  • 스팬 만들기
  • 중첩 스팬 만들기
  • 스팬 속성 설정
  • 이벤트로 스팬 만들기
  • 링크로 스팬 만들기

샘플링 구성

trace가 샘플링되는 경우를 구성하는 방법은 OpenTelemetry 샘플러를 참조하세요. 이 페이지에서는 사용 가능한 샘플링 옵션을 설명합니다.

샘플 애플리케이션

샘플 애플리케이션은 TraceExporterExample.java를 참조하세요.

플랫폼 구성

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

Google Cloud에서 실행

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

지원되는 Google Cloud 환경 목록은 환경 지원을 참조하세요.

다음 구성에서는 기본 액세스 범위 설정이 Cloud Trace API를 사용 설정합니다.

  • App Engine 가변형 환경
  • App Engine 표준 환경

  • Google Kubernetes Engine(GKE)

  • Compute Engine

  • Cloud Run

커스텀 액세스 범위를 사용하는 경우 Cloud Trace API 액세스 범위가 사용 설정되어 있는지 확인해야 합니다.

  • Google Cloud Console을 사용하여 환경의 액세스 범위를 구성하는 방법에 대한 자세한 내용은 Google Cloud 프로젝트 구성을 참조하세요.

  • gcloud 사용자의 경우 --scopes 플래그를 사용하여 액세스 범위를 지정하고 trace.append Cloud Trace API 액세스 범위를 포함합니다. 예를 들어 Cloud Trace API만 사용 설정된 GKE 클러스터를 만들려면 다음을 수행합니다.

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

로컬 및 기타 위치에서 실행

애플리케이션이 Google Cloud 외부에서 실행되는 경우 클라이언트 라이브러리에 사용자 인증 정보를 서비스 계정 형식으로 제공해야 합니다. 서비스 계정에는 Cloud Trace 에이전트 역할이 포함되어야 합니다. 자세한 내용은 서비스 계정 만들기를 참조하세요.

Google Cloud 클라이언트 라이브러리는 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하여 애플리케이션의 사용자 인증 정보를 찾습니다. 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"

trace 보기

배포 후에는 Cloud Console Trace 뷰어에서 trace를 볼 수 있습니다.

Trace 뷰어 페이지로 이동

문제 해결

Cloud Trace 문제 해결에 대한 자세한 내용은 문제 해결 페이지를 참조하세요.

리소스