Agentic AI/Google ADK

29. 평가(4.x)- OpenTelemetry 패키지와 Google ADK 사이의 버전 의존성 충돌(Dependency Conflict)

아톨 2026. 11. 10. 17:33

설치한 패키지를 모두 삭제하거나 가상환경을 새로 만들 필요 없이, OpenTelemetry의 핵심 패키지 버전을 조정하면 해결할 수 있습니다. 우선 현재 상황을 정확하게 이해한 다음, 안전하게 수정하고 정상 작동 여부까지 확인해 보겠습니다.

1. 현재 오류의 원인

실행 결과를 보면 다음과 같습니다.

google-adk 2.13.0 has requirement
opentelemetry-api<=1.44,>=1.39,
but you have opentelemetry-api 1.45.2.

google-adk 2.13.0 has requirement
opentelemetry-sdk<=1.44,>=1.39,
but you have opentelemetry-sdk 1.45.2.

핵심은 다음과 같습니다.


패키지 Google ADK 요구사항 현재 설치 버전 상태
opentelemetry-api 1.39 ~ 1.44 1.45.2
충돌
opentelemetry-sdk 1.39 ~ 1.44 1.45.2
충돌

Google ADK 2.13.0은 OpenTelemetry API와 SDK의 버전이 1.44 이하이어야 한다고 명시하고 있습니다. 그런데 이번에 OTLP Exporter 등을 설치하는 과정에서 의존성 해결기가 API와 SDK를 1.45.2로 올린 것입니다.

즉, 문제는 OpenTelemetry 자체가 아니라 Google ADK가 허용하는 버전 범위를 초과했다는 것입니다.

2. 권장 해결 방법: API와 SDK 버전을 1.44로 고정

현재 가상환경을 그대로 유지하면서 다음 명령어를 실행하는 방법을 추천합니다.

PowerShell에서 실행하세요.

python -m pip install `
    "opentelemetry-api==1.44.0" `
    "opentelemetry-sdk==1.44.0"

왜 1.44.0인가?

  • Google ADK 2.13.0의 허용 범위에 포함됩니다.

  • 현재 설치된 다른 OpenTelemetry 패키지를 무조건 제거할 필요가 없습니다.

  • API와 SDK의 버전을 일치시켜 관리하기 쉽습니다.

단, 이 두 패키지만 낮추면 모든 충돌이 해결된다고 미리 단정할 수는 없습니다. 이후 pip check 결과를 확인해야 합니다.

3. 설치된 패키지 전체를 함께 점검하기

한 가지 더 중요한 점이 있습니다.

이번에 설치한 패키지는 API와 SDK뿐 아니라 Exporter와 Instrumentation 패키지도 포함하고 있습니다. 따라서 핵심 패키지만 내리는 것보다 전체 의존성을 함께 점검하는 것이 좋습니다.

OpenTelemetry는 다음과 같은 구조입니다. 

여기서 중요한 것은 API와 SDK의 버전 호환성입니다. Exporter는 API/SDK와 별도의 패키지이지만, 이들 역시 의존성 조건을 가지고 있습니다.

공식 문서에서도 API, SDK, Exporter, Instrumentation을 별도 확장 패키지로 관리하는 구조를 설명하고 있습니다.

4. 추천하는 실제 수정 순서

현재 가상환경을 유지하면서 다음 순서로 진행하세요.

 

① 현재 설치 상태 백업

python -m pip freeze > requirements_before_otel_fix.txt

나중에 문제가 생기면 기존 설치 상태를 참고할 수 있습니다.

 

② API와 SDK 버전 조정

python -m pip install `
    "opentelemetry-api==1.44.0" `
    "opentelemetry-sdk==1.44.0"

 

③ 의존성 검사

python -m pip check

여기서 다음과 같이 나오면 정상입니다.

No broken requirements found.

만약 새로운 충돌이 나타나면 추가 패키지를 무작정 삭제하지 말고, 충돌 메시지를 확인해야 합니다.

 

④ 그래도 충돌이 발생한다면

여기서 주의할 사항이 하나 있습니다.

OpenTelemetry Python의 버전 체계는 다음처럼 연결되어 있습니다.

API/SDK
 Instrumentation 계열
1.42.x 0.63b 계열
1.43.x 0.64b 계열
1.44.x 0.65b 계열
1.45.x 0.66b 계열

따라서 API/SDK를 1.44로 고정했는데도 Instrumentation 관련 충돌이 생긴다면, SQLite3 등의 패키지도 0.65b 계열로 맞추는 방법이 있습니다.

 

예를 들어 다음과 같이 설치할 수 있습니다.

python -m pip install `
    "opentelemetry-api==1.44.0" `
    "opentelemetry-sdk==1.44.0" `
    "opentelemetry-exporter-otlp-proto-grpc==1.44.0" `
    "opentelemetry-exporter-otlp-proto-http==1.44.0" `
    "opentelemetry-instrumentation-sqlite3==0.65b0"

단, Google GenAI 및 Vertex AI Instrumentation은 별도 의존성도 있으므로 이 명령은 전체 패키지 검증을 대체하지 않습니다.

5. 최종 설치 상태 확인

아래 명령어를 차례대로 실행해 주세요.

 

① OpenTelemetry 패키지 버전 확인

python -m pip list | findstr opentelemetry

 

② 전체 의존성 검사

python -m pip check

* 이 단계에서 에러가 발생하면 7번으로 바로 넘어갑니다.

 

③ 실제 Python import 테스트

python -c "from opentelemetry import trace; from opentelemetry.sdk.trace import TracerProvider; from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter; print('OpenTelemetry import OK')"

정상이라면 다음 결과가 나옵니다.

OpenTelemetry import OK

 

④ ADK 버전 확인

python -c "import google.adk; print('Google ADK import OK')"

6. 앞으로의 개발 환경 관리에 대한 제안

이번에 진행하는 OpenTelemetry 중앙집중형 관측체계 테스트는 ADK 학습 프로젝트의 중요한 기반이 될 것입니다.

앞으로는 패키지 버전을 매번 최신으로 설치하기보다는 검증된 버전 조합을 기록해 두는 것을 추천합니다.

예를 들어 requirements-otel.txt 파일을 만들어 관리하는 것입니다.

google-adk==2.13.0

opentelemetry-api==1.44.0
opentelemetry-sdk==1.44.0

opentelemetry-exporter-otlp-proto-grpc==1.44.0
opentelemetry-exporter-otlp-proto-http==1.44.0

opentelemetry-instrumentation-sqlite3==0.65b0
opentelemetry-instrumentation-google-genai>=0.7b1,<2
opentelemetry-instrumentation-vertexai>=2.0b0

이것은 시작점이며, 실제로 pip check를 통과한 버전을 최종 확정해야 합니다. 특히 베타 버전은 향후 변경될 수 있습니다.

참고로 Google Cloud의 ADK 관측성 가이드에서도 Google GenAI, SQLite3, Vertex AI 계측과 OTLP Exporter를 조합하여 설치하도록 안내하고 있습니다.

 

공식 참고 자료:

7. 5항2의 전체 의존성 검사 에러시

(venv) PS C:\Dev\book_agentic_ai\adk_> python -m pip freeze > requirements_before_otel_fix.txt
(venv) PS C:\Dev\book_agentic_ai\adk_> python -m pip install `
>> "opentelemetry-api==1.44.0" `
>> "opentelemetry-sdk==1.44.0"

(venv) PS C:\Dev\book_agentic_ai\adk_> python -m pip check
opentelemetry-exporter-otlp-common 0.66b2 has requirement opentelemetry-sdk~=1.45.2, but you have opentelemetry-sdk 1.44.0.
opentelemetry-exporter-otlp-proto-grpc 1.45.2 has requirement opentelemetry-sdk~=1.45.2, but you have opentelemetry-sdk 1.44.0.
opentelemetry-exporter-otlp-proto-http 1.45.2 has requirement opentelemetry-sdk~=1.45.2, but you have opentelemetry-sdk 1.44.0.
opentelemetry-instrumentation 0.66b2 has requirement opentelemetry-semantic-conventions==0.66b2, but you have opentelemetry-semantic-conventions 0.65b0.
opentelemetry-instrumentation-dbapi 0.66b2 has requirement opentelemetry-semantic-conventions==0.66b2, but you have opentelemetry-semantic-conventions 0.65b0.

 

이제 충돌의 원인이 훨씬 명확해졌습니다.

앞서 API와 SDK를 1.44.0으로 낮춘 것은 Google ADK의 요구사항을 맞추기 위한 올바른 방향이었습니다. 그런데 이번에는 기존에 설치되어 있던 OTLP Exporter와 Instrumentation 패키지들이 여전히 1.45.2 / 0.66b2 계열을 요구하고 있는 것이 확인됐습니다. 즉, 현재는 서로 다른 두 세대의 OpenTelemetry 패키지가 혼합되어 있습니다.

 

이 문제는 패키지 몇 개를 개별적으로 낮추는 것보다, 관련 패키지 전체를 동일한 버전 계열로 맞추는 것이 좋습니다.

8. 현재 충돌 상태 분석

실행 결과를 정리하면 다음과 같습니다.

패키지
 현재 상태 문제
opentelemetry-api 1.44.0 정상 범위
opentelemetry-sdk 1.44.0 정상 범위
otlp-exporter-common 0.66b2 SDK 1.45.2 요구
otlp-exporter-grpc 1.45.2 SDK 1.45.2 요구
otlp-exporter-http 1.45.2 SDK 1.45.2 요구
instrumentation 0.66b2 semantic-conventions 0.66b2 요구
instrumentation-dbapi 0.66b2 semantic-conventions 0.66b2 요구
semantic-conventions 0.65b0 버전 불일치

따라서 다음과 같이 정리해야 합니다.

 

9. 이번에는 관련 패키지를 한 번에 정렬하겠습니다

OpenTelemetry 공식 릴리스 체계를 확인하면 다음과 같습니다.

  • API / SDK 1.44.0과 Instrumentation 0.65b0은 같은 릴리스 계열입니다.

  • API / SDK 1.45.x와 Instrumentation 0.66b 계열은 그다음 릴리스 계열입니다.

여기서 한 가지 구분해야 합니다. OTLP gRPC/HTTP Exporter는 1.44.0이고, OTLP Common 및 일반 Instrumentation은 0.65b0입니다. 모든 패키지에 동일한 버전 번호를 적용하는 것은 아닙니다.

PowerShell에서 다음 명령어를 실행해 보세요.

python -m pip install --upgrade `
    "opentelemetry-api==1.44.0" `
    "opentelemetry-sdk==1.44.0" `
    "opentelemetry-exporter-otlp-common==0.65b0" `
    "opentelemetry-exporter-otlp-proto-grpc==1.44.0" `
    "opentelemetry-exporter-otlp-proto-http==1.44.0" `
    "opentelemetry-instrumentation==0.65b0" `
    "opentelemetry-instrumentation-dbapi==0.65b0" `
    "opentelemetry-instrumentation-sqlite3==0.65b0" `
    "opentelemetry-semantic-conventions==0.65b0"

이 명령은 현재 확인된 충돌 패키지를 중심으로 버전을 정렬합니다.

Google GenAI 및 Vertex AI Instrumentation은 일단 기존 버전을 유지합니다. 이 두 패키지까지 강제로 낮추지는 않겠습니다.

10. 설치 후 반드시 검증하기

설치가 끝나면 다음 순서로 확인하세요.

 

① 의존성 충돌 검사

python -m pip check

기대 결과:

No broken requirements found.

 

② OpenTelemetry 패키지 버전 확인

python -m pip list | findstr opentelemetry

 

특히 아래 항목을 확인하겠습니다.

패키지
 기대 버전
opentelemetry-api 1.44.0
opentelemetry-sdk 1.44.0
opentelemetry-exporter-otlp-common 0.65b0
opentelemetry-exporter-otlp-proto-grpc 1.44.0
opentelemetry-exporter-otlp-proto-http 1.44.0
opentelemetry-instrumentation 0.65b0
opentelemetry-semantic-conventions 0.65b0

③ ADK 실행 확인

python -c "import google.adk; print('Google ADK OK')"
adk --version

 

 
반응형
저작자표시 비영리 변경금지 (새창열림)