Google Cloud로 텔레메트리 전송

gcp의 adk-telemetry 기능은 트레이스를 Google Cloud Observability(Cloud Trace)로 직접 내보내고, Cloud Logging이 기본적으로 파싱하는 구조화된 JSON 로그를 기록합니다. 여기에는 심각도, 메시지, 트레이스 상관관계가 포함됩니다.

기능 활성화

[dependencies]
adk-telemetry = { version = "2.1.0", features = ["gcp"] }

또는 우산 크레이트를 통해 활성화할 수 있습니다(gcp-telemetry도 gemini-agent-platform 메타 기능의 일부입니다).

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gcp-telemetry"] }

Google Cloud로 직접 내보내기

init_with_gcp는 gRPC를 통해 스팬을 https://telemetry.googleapis.com로 내보내며, Application Default Credentials(ADC)에서 발급된 Bearer 토큰과 x-goog-user-project 헤더를 사용해 각 요청을 인증합니다. 백그라운드 작업은 5분마다 토큰을 다시 발급하므로, 장시간 실행되는 에이전트도 토큰 만료 후 계속 내보낼 수 있습니다.

use adk_telemetry::init_with_gcp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Requires GOOGLE_CLOUD_PROJECT and Application Default Credentials.
    init_with_gcp("my-agent").await?;

    // Your agent code here

    adk_telemetry::shutdown_telemetry();
    Ok(())
}

요구 사항:

참고: 이 경로는 trace만 내보냅니다. 아래의 collector sidecar를 통해 metric을 라우팅하세요.

GCP 리소스 감지

init_with_gcp는 배포된 container에서 플랫폼이 설정하는 environment variable을 기반으로 OpenTelemetry 리소스 attribute를 파생합니다:

GOOGLE_CLOUD_AGENT_ENGINE_ID은 Vertex AI Agent Engine이 배포된 컨테이너에서 설정하는 숫자만으로 된 엔진 ID입니다. gcp.agent_engine은 OpenTelemetry 시맨틱 규칙에서 가져온 표준 cloud.platform 값입니다(2025년 10월에 업스트림에 추가됨).

동일한 감지 기능을 독립적으로 사용하여 자체 파이프라인을 구성할 수도 있습니다.

use adk_telemetry::gcp_resource_attributes;

let attributes = gcp_resource_attributes("my-agent");

Cloud Logging을 위한 구조화된 JSON 로깅

init_json_logging은 stdout에 한 줄마다 하나의 JSON 객체를 기록하므로, Cloud Logging이 불투명한 텍스트 페이로드로 표시하는 대신 심각도 및 trace 필드를 파싱합니다. init_with_gcp는 동일한 형식을 자동으로 설치합니다.

use adk_telemetry::init_json_logging;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_json_logging()?;

    tracing::info!(user.id = "u1", "request handled");
    Ok(())
}

생성되는 필드:

Trace 상관관계 필드에는 동일한 subscriber에 OpenTelemetry 레이어와 GOOGLE_CLOUD_PROJECT가 필요합니다. init_with_gcp는 두 가지를 모두 제공하므로 Cloud Trace 패널에 로그 항목이 인라인으로 표시됩니다.

대안: 사이드카로 OTLP를 Collector에 전달

직접적인 API 액세스를 사용할 수 없거나 메트릭도 필요한 경우, OpenTelemetry Collector를 사이드카로 실행하고 표준 OTLP exporter가 해당 Collector를 가리키도록 설정합니다.

use adk_telemetry::init_with_otlp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_with_otlp("my-agent", "http://localhost:4317")?;

    // Your agent code here

    adk_telemetry::shutdown_telemetry();
    Ok(())
}

Google Cloud로 전달하는 Collector 구성입니다(otel-collector-config.yaml, contrib 배포판의 googlecloud exporter 사용):

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    send_batch_size: 200
    timeout: 5s
  resourcedetection:
    detectors: [env, gcp]

exporters:
  googlecloud:
    project: my-project

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [googlecloud]
    metrics:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [googlecloud]

개발을 위해 로컬에서 실행합니다.

docker run --rm -p 4317:4317 \
  -v ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  -v ~/.config/gcloud:/root/.config/gcloud \
  otel/opentelemetry-collector-contrib:latest

경로 선택

관련 항목

• 텔레메트리 - 핵심 텔레메트리 설정 및 스팬 헬퍼
• 배포 - 프로덕션 텔레메트리 설정