Google Cloud Java 애플리케이션을 위한 강력한 모니터링, 로깅, 진단 기능을 제공합니다.
Java 클라이언트 라이브러리는 추적, 측정항목, 로깅 데이터를 내보내도록 계측됩니다. 계측은 선택사항입니다. 명시적으로 사용 설정해야 합니다. 이 문서에서는 사용 가능한 신호와 이를 사용 설정하는 방법을 설명합니다.
사용 가능한 신호
골든 시그널에는 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-java).gcp.client.version: 클라이언트 라이브러리 버전.gcp.client.artifact: 특정 모듈 경로 (예:com.google.cloud:google-cloud-secretmanager).gcp.resource.destination.id: 작업이 수행되는 리소스의 ID입니다.gcp.errors.domain: 실행 가능한 오류 로그의 오류 도메인입니다.gcp.errors.metadata.<key>: 실패한 요청의 추가 오류 메타데이터 키 (평면화됨).
표준 속성의 전체 목록은 OpenTelemetry HTTP 및 gRPC 시맨틱 규칙을 참조하세요.
원격 분석 사용 설정
민감한 정보를 보호하기 위해 원격 분석 신호는 기본적으로 사용 중지되어 있습니다. 이를 사용 설정하려면 명시적으로 선택해야 합니다.
추적 및 측정항목
생성된 Java 클라이언트 라이브러리에서 초기화 중에 클라이언트 설정에 적절한 추적기 팩토리를 제공하여 추적 및 측정항목을 프로그래매틱 방식으로 사용 설정해야 합니다.
- 추적:
OpenTelemetryTracingFactory로 클라이언트를 구성합니다. - 측정항목:
OpenTelemetryMetricsFactory로 클라이언트를 구성합니다. - 둘 다: 추적과 측정항목을 모두 사용 설정하려면 두 팩토리를 모두 래핑하는
CompositeTracerFactory로 클라이언트를 구성합니다.
로깅
실행 가능한 오류 로그는 핵심 ApiTracer 프레임워크에 직접 통합됩니다. 클라이언트 라이브러리 전반에서 실행 가능한 오류 로그를 전역적으로 사용 설정하려면 다음 환경 변수를 사용하세요. Google Cloud
export GOOGLE_SDK_JAVA_LOGGING=true
Trace 컨텍스트 전파
Java 클라이언트 라이브러리의 trace 컨텍스트 전파에는 추적이 명시적으로 사용 설정되어 있어야 합니다.
trace 생성이 사용 설정되어 있고 (예: OpenTelemetryTracingFactory 구성) 클라이언트 라이브러리 메서드가 호출될 때 애플리케이션에 현재 컨텍스트에서 활성 OpenTelemetry 스팬이 있는 경우 라이브러리는 이를 사용하여 나가는 요청의 추적 컨텍스트를 제공합니다. 이렇게 하면 애플리케이션 수준 trace를 백엔드 서비스 로그 및 동작과 상호 연결할 수 있습니다.
원격 분석 내보내기
클라이언트 라이브러리에서 원격 분석을 사용 설정하면 이 데이터를 수집하여 관측 가능성 백엔드로 내보내도록 애플리케이션을 구성해야 합니다.
추적 및 측정항목
Java 클라이언트 라이브러리에서 생성된 trace 및 측정항목을 내보내려면 선호하는 내보내기 도구 (예: OTLP)로 OpenTelemetry SDK를 초기화하고 애플리케이션에서 전역 텍스트 맵 전파기를 설정합니다.
OpenTelemetry 데이터를 Cloud Monitoring 또는 Cloud Trace로 수집하고 내보내는 방법에 대한 자세한 내용은 계측 접근 방식 선택을 참조하세요.
로깅
Java 클라이언트 라이브러리는 SLF4J 및 java.util.logging과 같은 표준 로깅 프레임워크를 사용합니다. GOOGLE_SDK_JAVA_LOGGING=true가 설정되면 실행 가능한 오류 로그가 DEBUG 수준에서 내보내집니다.
이러한 구조화된 로그를 Cloud Logging으로 라우팅하려면 JSON을 표준 출력 (stdout)에 쓰도록 로깅 프레임워크 (예: Logback)를 구성합니다. Google Kubernetes Engine 또는 Cloud Run과 같은 환경에 배포하는 경우 기본 제공 에이전트가 이러한 로그를 자동으로 스크래핑합니다.
trace 상관관계를 포함하여 Cloud Logging 호환 JSON을 출력하도록 Logback 또는 java.util.logging을
구성하는 방법에 대한 자세한 안내는
Java용 구조화된 로깅 구성을 참조하세요.