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

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

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

사용 가능한 신호

Rust 클라이언트 라이브러리는 다음 신호를 생성하도록 계측됩니다.

  1. 각 논리적 클라이언트 요청에 대한 INFO 범위입니다. 일반적으로 클라이언트 구조체의 단일 메서드 호출은 이러한 범위를 가져옵니다 (예: SecretManagerService 클라이언트에서 access_secret_version 호출).
  2. 각 논리적 클라이언트 요청의 경과 시간을 측정하는 히스토그램 측정항목입니다. 기본 측정항목은 gcp.client.request.duration입니다.
  3. 실패한 각 논리적 클라이언트 요청에 대한 WARN 로그입니다.
  4. 각 하위 수준 RPC 시도에 대한 INFO 범위입니다. 일반적으로 클라이언트 구조체의 단일 메서드는 이러한 스팬을 가져오지만 라이브러리가 RPC를 재시도해야 하는 경우 더 많을 수 있습니다.
  5. 실패한 각 하위 수준 시도에 대한 DEBUG 로그입니다.

이러한 범위와 로그는 추가 Google Cloud 속성과 함께 OpenTelemetry Semantic 규칙을 따릅니다. 범위와 로그는 모두 프로덕션 모니터링에 적합해야 합니다.

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

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

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

라이브러리에는 각 요청에 대한 DEBUG 범위도 있습니다. 여기에는 전체 요청 본문, 성공한 요청의 전체 응답 본문, 실패한 요청의 세부정보가 포함된 전체 오류 메시지가 포함됩니다.

요청 또는 응답에 민감한 정보가 포함될 수 있으므로 프로덕션 환경에서 사용 설정하기 전에 이러한 요청 및 응답의 콘텐츠를 고려하세요.

이러한 DEBUG 스팬은 클라이언트 라이브러리 크레이트 다음에 ::tracing을 타겟으로 사용하고 (예: google_cloud_secretmanager_v1::tracing) 메서드 이름을 스팬 이름으로 사용합니다 (예: access_secret_version). 이름, 타겟 또는 둘 다 사용하여 필터를 설정할 수 있습니다.

원격 분석 사용 설정

민감한 정보를 보호하기 위해 원격 분석 신호는 기본적으로 사용 중지됩니다.

Rust에서는 trace, 측정항목, 로그를 내보내도록 클라이언트를 구성해야 하며 이러한 신호를 외부 서비스로 전송하도록 구독자와 내보내기 도구를 구성해야 합니다.

클라이언트를 구성하려면 다음 환경 변수를 설정하면 됩니다.

export GOOGLE_CLOUD_RUST_LOGGING=true

또는 클라이언트 빌더에서 .with_tracing() 메서드를 사용하여 클라이언트를 빌드할 때 추적을 프로그래매틱 방식으로 명시적으로 사용 설정할 수 있습니다.

use google_cloud_secretmanager_v1::client::SecretManagerService;

let client = SecretManagerService::builder()
    .with_tracing()
    .build()
    .await?;

Trace 컨텍스트 전파

Rust 클라이언트 라이브러리는 trace 생성을 명시적으로 사용 설정하지 않은 경우에도 활성 trace 컨텍스트를 Google Cloud 서비스에 자동으로 전파합니다 .with_tracing().

tracing-opentelemetry 또는 opentelemetry 크레이트를 사용하여 클라이언트 라이브러리의 추적 컨텍스트를 제공합니다.

원격 분석 내보내기

클라이언트 라이브러리에서 원격 분석을 사용 설정하면 이 데이터를 관측 가능성 서비스로 수집하고 내보내도록 애플리케이션을 구성해야 합니다. Rust 클라이언트 라이브러리는 기본적으로 추적 생태계를 사용합니다.

추적

클라이언트 라이브러리에서 생성된 tracing 범위를 Google Cloud OpenTelemetry로 내보내려면 데이터를 OpenTelemetry 내보내기 도구 (예: OTLP)로 파이프하는 애플리케이션에서 Subscriber를 구성해야 합니다.

tracing-opentelemetry 및 opentelemetry-otlp 크레이트를 사용하여 내보내기 도구를 구성합니다.

use google_cloud_secretmanager_v1::client::SecretManagerService;
use opentelemetry::trace::TracerProvider as _;
use tracing_subscriber::Registry;
use tracing_subscriber::layer::SubscriberExt;

pub async fn sample() -> anyhow::Result<()> {
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .build()?;
    let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder()
        .with_batch_exporter(exporter)
        .build();
    let tracer = provider.tracer("example");

    // Create a tracing layer that sends data to an OpenTelemetry Collector running on localhost.
    let telemetry = tracing_opentelemetry::layer().with_tracer(tracer);

    // Register the subscriber globally
    let subscriber = Registry::default().with(telemetry);
    tracing::subscriber::set_global_default(subscriber)?;

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

측정항목

측정항목을 내보내려면 클라이언트를 초기화하기 전에 애플리케이션에 전역 OpenTelemetry MeterProvider를 설치해야 합니다. 클라이언트 라이브러리는 이를 자동으로 사용하여 측정항목 데이터를 기록하고 내보냅니다.

OpenTelemetry 데이터를 Cloud Monitoring 또는 Cloud Trace로 수집하고 내보내는 방법에 관한 자세한 내용은 계측 접근 방식 선택을 참조하세요.

로깅

Rust 클라이언트 라이브러리는 tracing 크레이트를 사용하여 WARN 및 DEBUG 수준에서 실행 가능한 오류 로그를 내보냅니다. 적절한 포맷터를 사용하는 경우 내보낸 로그에는 trace와의 원활한 상관관계를 보장하기 위해 trace ID와 스팬 ID가 포함됩니다.

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

다음 예에서는 WARN 수준 로그만 캡처하고 라우팅하도록 구독자를 구성합니다.

use google_cloud_secretmanager_v1::client::SecretManagerService;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::util::SubscriberInitExt;

pub async fn sample() -> anyhow::Result<()> {
    // Enable all `WARN` logs to include failed client requests in all client libraries.
    let filter = tracing_subscriber::EnvFilter::new("warn");

    tracing_subscriber::registry()
        .with(filter)
        .with(tracing_subscriber::fmt::layer().json())
        .init();

    let _client = SecretManagerService::builder()
        .with_tracing()
        .build()
        .await?;

    Ok(())
}

JSON 포맷터에서 OpenTelemetry trace 상관관계 데이터 (logging.googleapis.com/trace 등)를 구성하는 방법에 관한 자세한 안내는 수집기 기반 계측 샘플 개요를 참조하세요.