자바에 Cloud Trace 설정

OpenCensus를 사용하여 자바 애플리케이션에 Cloud Trace를 사용 설정할 수 있습니다. OpenCensus는 여러 백엔드를 통해 작동하는 trace 및 측정항목 데이터를 수집하기 위한 계측 라이브러리 집합입니다. 자바용 OpenCensus에 대한 최신 세부정보, 추가 문서, 예시를 보려면 census-instrumentation/opencensus-java로 이동합니다.

라이브러리 설치

추적을 수집하려면 OpenCensus 추적 기능과 Stackdriver 내보내기 기능을 애플리케이션의 Maven 또는 Gradle 파일에 추가합니다.

전문가

<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-api</artifactId>
  <version>0.27.1</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-trace-stackdriver</artifactId>
  <version>0.27.1</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>0.27.1</version>
  <scope>runtime</scope>
</dependency>
<dependency>
   <groupId>joda-time</groupId>
   <artifactId>joda-time</artifactId>
   <version>2.10.6</version>
</dependency>

Gradle

compile 'io.opencensus:opencensus-api:0.26.0'
compile 'io.opencensus:opencensus-exporter-trace-stackdriver:0.26.0'
runtime 'io.opencensus:opencensus-impl:0.26.0'

Stackdriver 내보내기 구성

수집된 Trace 데이터를 내보내려면 StackdriverTraceExporter 객체를 사용합니다.

public static void createAndRegisterGoogleCloudPlatform(String projectId) throws IOException {
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder().setProjectId(projectId).build());
}

Google Cloud 인프라에서 실행하는 경우 setProjectID를 호출하고 Google Cloud 프로젝트 ID를 제공할 필요가 없습니다. 이 필드를 설정하지 않으면 자바용 클라이언트 라이브러리가 Google Cloud 메타데이터 서버에서 이 데이터를 자동으로 수집합니다.

Google Cloud 인프라에서 실행하지 않는 경우 애플리케이션에 Google Cloud 프로젝트 ID를 제공해야 합니다.

Google Cloud 프로젝트 ID를 명시적으로 설정하지 않으면 google-cloud 자바 라이브러리가 환경 변수 GOOGLE_CLOUD_PROJECT의 설정 여부를 자동으로 확인합니다. 이 변수가 설정된 경우 라이브러리는 GOOGLE_CLOUD_PROJECT 값을 Google Cloud 프로젝트 ID로 사용합니다.

자세한 내용은 google-cloud-library 프로젝트 ID 지정을 참조하세요. 환경 변수를 설정하려면 다음을 수행하세요.

Linux 또는 macOS

export GOOGLE_CLOUD_PROJECT=your-project-id

Windows

set GOOGLE_CLOUD_PROJECT=your-project-id

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"

커스텀 Trace 스팬 추가

OpenCensus 라이브러리에는 널리 사용되는 여러 웹 프레임워크 및 RPC 프레임워크에 대한 자동 통합이 포함되어 있지만 커스텀 trace를 만들 수도 있습니다.

private static final Tracer tracer = Tracing.getTracer();

public static void doWork() {
  // Create a child Span of the current Span.
  try (Scope ss = tracer.spanBuilder("MyChildWorkSpan").startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

private static void doInitialWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Doing initial work");
  // ...
}

private static void doFinalWork() {
  // ...
  tracer.getCurrentSpan().addAnnotation("Hello world!");
  // ...
}

Cloud Logging과의 통합 구성

Cloud Trace 데이터를 Cloud Logging으로 보내는 방법에 대한 자세한 내용은 Cloud Logging과 통합을 참조하세요.

전체 샘플링 사용 설정

기본적으로 10,000개의 trace 중 1개만 샘플링됩니다.

개발자 환경에서는 이 샘플링 레이트가 너무 낮아 trace 데이터를 보기 힘든 경우가 있습니다. 모든 trace를 샘플링하려면 alwaysSample 옵션을 사용합니다.

전체 샘플링을 사용 설정하려면 setSampler 메서드를 사용하고 alwaysSample 옵션을 지정합니다.

public static void doWorkFullSampled() {
  try (Scope ss =
      tracer
          .spanBuilder("MyChildWorkSpan")
          .setSampler(Samplers.alwaysSample())
          .startScopedSpan()) {
    doInitialWork();
    tracer.getCurrentSpan().addAnnotation("Finished initial work");
    doFinalWork();
  }
}

자동 인증 재정의

자동 인증 및 프로젝트 선택을 재정의할 수 있습니다. 예를 들어 다음 샘플은 사용자 인증 정보가 생성 시간으로부터 60초 후에 만료되는 내보내기를 만드는 방법을 보여줍니다.

public static void createAndRegisterWithToken(String accessToken) throws IOException {
  Date expirationTime = DateTime.now().plusSeconds(60).toDate();

  GoogleCredentials credentials =
      GoogleCredentials.create(new AccessToken(accessToken, expirationTime));
  StackdriverTraceExporter.createAndRegister(
      StackdriverTraceConfiguration.builder()
          .setProjectId("MyStackdriverProjectId")
          .setCredentials(credentials)
          .build());
}

플랫폼 구성

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

Google Cloud에서 실행

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

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

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

  • Google Kubernetes Engine(GKE)

  • Compute Engine

커스텀 액세스 범위를 사용하는 경우 Cloud Trace API 액세스 범위가 사용 설정되어 있는지 확인해야 합니다. 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"

추적 보기

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

추적 뷰어 페이지로 이동

문제해결

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

리소스