OpenTelemetry 추적을 사용하면 일괄 처리, 임대 관리, 흐름 제어와 같은 다양한 Pub/Sub 클라이언트 라이브러리 작업의 지연 시간을 식별하고 추적할 수 있습니다. 이 정보를 수집하면 클라이언트 라이브러리 문제를 디버깅하는 데 도움이 됩니다.
OpenTelemetry 추적의 잠재적인 사용 사례는 다음과 같습니다.
- 서비스의 게시 지연 시간이 평소보다 깁니다.
- 메시지 재전송 횟수가 많습니다.
- 구독자 클라이언트의 콜백 함수가 변경되어 처리에 평소보다 시간이 더 오래 걸립니다.
시작하기 전에
OpenTelemetry를 구성하기 전에 다음 태스크를 완료합니다.
- 클라이언트 라이브러리 중 하나를 사용하여 Pub/Sub를 설정합니다.
- OpenTelemetry SDK를 설치하고 trace 내보내기 도구와 추적기 공급자를 설정합니다.
- Cloud Trace API를 사용 설정합니다.
- Cloud Observability trace를 읽는 방법을 알아봅니다.
필요한 역할
서비스 계정에 Cloud Trace로 trace를 내보내는 데 필요한 권한이 있는지 확인하려면 관리자에게 서비스 계정에 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
전체:
Cloud Trace 에이전트 (
roles/cloudtrace.agent)
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이러한 사전 정의된 역할에는 Cloud Trace로 trace를 내보내는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
Cloud Trace로 trace를 내보내려면 다음 권한이 필요합니다.
-
전체:
cloudtrace.traces.patch
관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 서비스 계정에 이러한 권한을 부여할 수도 있습니다.
OpenTelemetry 추적 워크플로
OpenTelemetry 추적을 설정하려면 Pub/Sub 클라이언트 라이브러리와 OpenTelemetry SDK를 사용합니다. SDK를 사용하려면 Pub/Sub 라이브러리에 연결하기 전에 trace 내보내기 도구와 추적기 공급자를 설정해야 합니다. 일부 라이브러리에서는 트레이서 공급자를 설정하는 것이 선택사항입니다.
Trace 내보내기 도구. OpenTelemetry SDK는 trace 내보내기 도구를 사용하여 trace를 전송할 위치를 결정합니다.
추적기 공급자. Pub/Sub 클라이언트 라이브러리는 추적기 공급자를 사용하여 trace를 만듭니다.
다음 단계에서는 추적을 설정하는 방법을 설명합니다.
- Cloud Trace OpenTelemetry 내보내기 도구를 인스턴스화합니다.
- 필요한 경우 OpenTelemetry SDK를 사용하여 추적기 공급자를 인스턴스화하고 등록합니다.
- OpenTelemetry 추적 사용 설정 옵션으로 클라이언트를 구성합니다.
- Pub/Sub 클라이언트 라이브러리를 사용하여 메시지를 게시합니다.
추적 작동 방식
게시되는 모든 메시지에 대해 클라이언트 라이브러리는 새 trace를 만듭니다. 이 trace는 메시지를 게시하는 순간부터 메시지가 확인될 때까지의 메시지 전체 수명 주기를 나타냅니다. trace는 작업 시간, 상위 스팬 및 하위 스팬, 연결된 스팬과 같은 정보를 캡슐화합니다.
trace는 루트 스팬과 이에 상응하는 하위 스팬으로 구성됩니다. 이러한 스팬은 클라이언트 라이브러리가 메시지를 처리할 때 수행하는 작업을 나타냅니다. 각 메시지 trace에는 다음이 포함됩니다.
- 게시의 경우 흐름 제어, 순서 키 예약, 일괄 처리, 게시 RPC 길이.
- 구독의 경우 동시 실행 제어, 순서 키 예약, 임대 관리.
게시에서 구독 측으로 정보를 전파하기 위해 클라이언트 라이브러리는 게시 측에 추적 관련 속성을 삽입합니다. 컨텍스트 전파 메커니즘은 추적이 사용 설정된 경우에만 사용 설정되며 googclient_ 프리픽스가 추가됩니다.
추적으로 메시지 게시
다음 코드 샘플에서는 Pub/Sub 클라이언트 라이브러리와 OpenTelemetry SDK를 사용하여 추적을 사용 설정하는 방법을 보여줍니다. 이 샘플에서는 추적 결과가 Cloud Trace로 내보내집니다.
고려사항
추적기 공급자를 인스턴스화할 때 OpenTelemetry SDK로 샘플링 레이트를 구성합니다. 이 비율에 따라 SDK에서 샘플링해야 하는 trace 수가 결정됩니다. 샘플링 레이트를 낮추면 결제 비용을 줄이고 서비스가 Cloud Trace 스팬 할당량을 초과하지 않도록 할 수 있습니다.
Go
C++
Python
이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Python API 참조 문서를 참조하세요.