Go 클라이언트 라이브러리에서 원격 분석 신호 사용 설정

Google Cloud Go 애플리케이션을 위한 강력한 모니터링, 로깅, 진단 기능을 제공합니다.

Go 클라이언트 라이브러리는 trace, 측정항목, 로깅 데이터를 내보내도록 계측됩니다. 계측은 선택사항이며 명시적으로 사용 설정해야 합니다. 이 문서에서는 사용 가능한 신호와 이를 사용 설정하는 방법을 설명합니다.

사용 가능한 신호

신호에는 OpenTelemetry 시맨틱 규칙을 준수하는 다음과 같은 원격 분석 데이터가 포함됩니다.

Trace: 클라이언트 라이브러리에서 수행한 네트워크 요청을 나타내는 하위 수준 HTTP/gRPC trace입니다.
측정항목: 지연 시간과 요청률을 추적하는 클라이언트 요청 측정항목입니다. 기본 측정항목은 gcp.client.request.duration입니다.
로그: 결국 성공적으로 재시도되더라도 전송 계층에서 실패한 요청에 대한 세부정보를 제공하는 DEBUG 수준 이상의 실행 가능한 오류 로그입니다.

신호에는 표준 OpenTelemetry 속성 (예: http.response.status_code 및 rpc.system.name)과 Google Cloud-특정 커스텀 속성이 포함되며, 이러한 속성 및 유사한 속성이 포함될 수 있습니다.

gcp.client.service: 서비스 이름 (예: pubsub 또는 storage).
gcp.client.repo: 클라이언트 라이브러리 저장소 (예: googleapis/google-cloud-go).
gcp.client.version: 클라이언트 라이브러리 버전.
gcp.client.artifact: 특정 모듈 경로 (예: cloud.google.com/go/secretmanager).
gcp.resource.destination.id: 작업이 수행되는 리소스의 ID.
gcp.errors.domain: 실행 가능한 오류 로그의 오류 도메인.
gcp.errors.metadata.<key>: 실패한 요청의 추가 오류 메타데이터 키 (평면화됨).

표준 속성의 전체 목록은 OpenTelemetry HTTP 및 gRPC 시맨틱 규칙을 참조하세요.

원격 분석 사용 설정

민감한 정보를 보호하기 위해 골든 시그널은 기본적으로 사용 중지되어 있습니다. 이를 사용 설정하려면 명시적으로 선택해야 합니다.

Go에서 다음 환경 변수를 사용하여 클라이언트 라이브러리 전반에서 trace, 측정항목, 로그를 전역적으로 사용 설정합니다. Google Cloud

# Enable trace generation (span emission)
export GOOGLE_SDK_GO_TRACING=true

# Enable metrics
export GOOGLE_SDK_GO_METRICS=true

# Enable logging
export GOOGLE_SDK_GO_LOGGING=true

Trace 컨텍스트 전파

Go 클라이언트 라이브러리는 trace 생성 (GOOGLE_SDK_GO_TRACING)이 사용 중지되어 있더라도 활성 trace 컨텍스트를 Google Cloud 서비스에 자동으로 전파합니다.

애플리케이션에 클라이언트 라이브러리 메서드에 전달된 context.Context에 활성 OpenTelemetry 스팬이 있는 경우 라이브러리는 이를 사용하여 나가는 요청의 trace 컨텍스트를 제공합니다. 이렇게 하면 클라이언트 측 스팬을 내보낼 필요 없이 애플리케이션 수준 trace를 백엔드 서비스 로그 및 동작과 상호 연결할 수 있습니다.

애플리케이션에서 전역 OpenTelemetry 텍스트 맵 전파기를 설정하여 클라이언트 라이브러리의 trace 컨텍스트를 제공합니다.

원격 분석 내보내기

클라이언트 라이브러리에서 원격 분석을 사용 설정하면 이 데이터를 관측 가능성 백엔드로 수집하고 내보내도록 애플리케이션을 구성해야 합니다.

Trace 및 측정항목

Go 클라이언트 라이브러리에서 생성된 trace 및 측정항목을 내보내려면 선호하는 내보내기 도구 (예: OTLP)로 OpenTelemetry SDK를 초기화하고 main.go에서 전역 텍스트 맵 전파기를 설정합니다.

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
    ctx := context.Background()

    // Initialize the exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        log.Fatalf("failed to initialize exporter: %v", err)
    }

    // Set up the tracer provider
    tp := trace.NewTracerProvider(trace.WithBatcher(exporter))
    defer func() {
        // Ensure all spans are flushed before exit
        if err := tp.Shutdown(ctx); err != nil {
            log.Fatalf("failed to shutdown TracerProvider: %v", err)
        }
    }()

    otel.SetTracerProvider(tp)

    // Set up the global propagator
    otel.SetTextMapPropagator(propagation.TraceContext{})

    // ... initialize Google Cloud client libraries ...
}

OpenTelemetry SDK를 Cloud Monitoring 또는 Cloud Trace에 연결하는 방법에 대한 자세한 내용은 Go용 Google Cloud Observability 가이드를 참조하세요.

로깅

Go 클라이언트 라이브러리는 slog를 사용하는 구조화된 로깅을 사용하여 DEBUG 수준에서 실행 가능한 오류를 내보냅니다. 로깅 프레임워크가 context.Context에서 trace ID와 스팬 ID를 추출하도록 구성된 경우 내보낸 로그에 trace ID와 스팬 ID가 자동으로 포함됩니다.

이러한 로그를 수신하려면 초기화 시 구성된 *slog.Logger를 클라이언트에 제공해야 합니다 (예: option.WithLogger() 사용).

이러한 구조화된 로그를 Cloud Logging으로 라우팅하려면 JSON을 표준 출력 (stdout)에 쓰도록 slog를 구성합니다. Google Kubernetes Engine 또는 Cloud Run과 같은 환경에 배포하는 경우 기본 제공 에이전트가 이러한 로그를 자동으로 스크레이핑합니다.

package main

import (
    "context"
    "log/slog"
    "os"

    "cloud.google.com/go/secretmanager/apiv1"
    "google.golang.org/api/option"
)

func main() {
    ctx := context.Background()

    // Configure slog to output JSON to stdout at the DEBUG level
    opts := &slog.HandlerOptions{Level: slog.LevelDebug}
    logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))

    // Provide the logger to the client
    client, err := secretmanager.NewClient(ctx, option.WithLogger(logger))
    if err != nil {
        // handle error
    }
    defer client.Close()
}

OpenTelemetry trace 컨텍스트를 매핑하고 Cloud Logging의 예상 페이로드 필드에 맞게 구조화된 JSON 로그 형식을 지정하는 방법에 대한 자세한 내용은 Go용 구조화된 로깅 구성을 참조하세요.