Go용 Cloud Trace 설정

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

패키지 설치

OpenCensus trace 패키지를 가져옵니다.

go get -u go.opencensus.io/trace

Stackdriver 내보내기 구성

수집된 Trace 데이터를 내보내려면 Stackdriver 내보내기를 사용합니다.


import (
	"log"
	"os"

	"contrib.go.opencensus.io/exporter/stackdriver"
	"go.opencensus.io/trace"
)

func main() {
	// Create and register a OpenCensus Stackdriver Trace exporter.
	exporter, err := stackdriver.NewExporter(stackdriver.Options{
		ProjectID: os.Getenv("GOOGLE_CLOUD_PROJECT"),
	})
	if err != nil {
		log.Fatal(err)
	}
	trace.RegisterExporter(exporter)
}

Google Cloud 인프라에서 실행하는 경우 Go용 클라이언트 라이브러리가 Google Cloud 메타데이터 서버에서 이 데이터를 자동으로 수집하므로 ProjectID 필드를 Google Cloud 프로젝트 ID로 설정할 필요가 없습니다.

Google Cloud 인프라에서 실행하지 않는 경우 ProjectID 필드를 Google Cloud 프로젝트 ID로 설정해야 합니다. 예제 코드에서는 환경 변수가 사용되었으며 이 변수를 읽기 위해 애플리케이션이 수정되었습니다.

Cloud Logging과의 통합 구성

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

플랫폼 구성

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"

Go용 샘플 Trace 애플리케이션


// Sample trace_quickstart traces incoming and outgoing requests.
package main

import (
	"log"
	"net/http"
	"os"

	"contrib.go.opencensus.io/exporter/stackdriver"
	"contrib.go.opencensus.io/exporter/stackdriver/propagation"
	"go.opencensus.io/plugin/ochttp"
	"go.opencensus.io/trace"
)

func main() {
	// Create and register a OpenCensus Stackdriver Trace exporter.
	exporter, err := stackdriver.NewExporter(stackdriver.Options{
		ProjectID: os.Getenv("GOOGLE_CLOUD_PROJECT"),
	})
	if err != nil {
		log.Fatal(err)
	}
	trace.RegisterExporter(exporter)

	// By default, traces will be sampled relatively rarely. To change the
	// sampling frequency for your entire program, call ApplyConfig. Use a
	// ProbabilitySampler to sample a subset of traces, or use AlwaysSample to
	// collect a trace on every run.
	//
	// Be careful about using trace.AlwaysSample in a production application
	// with significant traffic: a new trace will be started and exported for
	// every request.
	trace.ApplyConfig(trace.Config{DefaultSampler: trace.AlwaysSample()})

	client := &http.Client{
		Transport: &ochttp.Transport{
			// Use Google Cloud propagation format.
			Propagation: &propagation.HTTPFormat{},
		},
	}

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		req, _ := http.NewRequest("GET", "https://www.google.com", nil)

		// The trace ID from the incoming request will be
		// propagated to the outgoing request.
		req = req.WithContext(r.Context())

		// The outgoing request will be traced with r's trace ID.
		resp, err := client.Do(req)
		if err != nil {
			log.Fatal(err)
		}
		// Because we don't read the resp.Body, need to manually call Close().
		resp.Body.Close()
	})
	http.Handle("/foo", handler)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	log.Printf("Listening on port %s", port)

	// Use an ochttp.Handler in order to instrument OpenCensus for incoming
	// requests.
	httpHandler := &ochttp.Handler{
		// Use the Google Cloud propagation format.
		Propagation: &propagation.HTTPFormat{},
	}
	if err := http.ListenAndServe(":"+port, httpHandler); err != nil {
		log.Fatal(err)
	}
}

Trace 보기

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

Trace 뷰어 페이지로 이동

문제 해결

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

Go OpenCensus 내보내기 도구의 스팬 업로드 실패

다음은 내보내기 도구에서 사용된 Bundler 라이브러리가 애플리케이션이 생성 및 업로드하는 스팬 수를 관리할 수 없을 때 발생하는 오류의 예시입니다.

OpenCensus Stackdriver exporter: failed to upload span: buffer full
OpenCensus Stackdriver exporter: failed to upload 183 spans: buffer full

이 문제를 해결하려면 다음 중 하나 이상을 사용해 보세요.

  • traceExporter 생성자에 전달된 Options 구조체에서 TraceSpansBufferMaxBytes 필드의 값을 늘립니다. 이 선택적 필드는 버퍼링 스팬에 사용되는 최대 바이트 수를 지정합니다. 기본값은 8MB입니다.

  • traceExporter 생성자에 전달된 Options 객체에서 다음 필드의 값을 줄입니다.

    • BundleDelayThreshold: 이 선택적 필드는 내보내기 도구가 trace 스팬을 업로드하기 전에 대기할 수 있는 최대 시간을 지정합니다. 이 필드의 기본값은 2초입니다.

    • BundleCountThreshold: 이 선택적 필드는 버퍼링 가능한 스팬 수를 지정합니다. 이 필드의 기본값은 50입니다.

  • 스팬 수를 더 적게 내보냅니다. 내보내는 스팬 수를 줄이려면 전역 샘플러를 구성하거나 샘플러를 각 StartSpan에 전달합니다. 샘플 코드 및 이러한 구성에 대한 자세한 내용은 OpenCensus 샘플링을 참조하세요.

리소스