OpenTelemetry를 사용하여 ADK 애플리케이션 계측

이 문서에서는 에이전트 개발 키트(ADK) 프레임워크로 빌드된 AI 에이전트에 계측을 적용하는 방법을 설명합니다. ADK 프레임워크에는 에이전트의 주요 작업에서 원격 분석을 수집하는 OpenTelemetry 계측이 포함됩니다. 기본 제공 계측을 사용 설정하면 해당 계측에서 텍스트 프롬프트 및 에이전트 대답과 같은 정보를 Google Cloud 프로젝트로 전송합니다. 이 문서에서는 필요한 변경사항을 설명하고 샘플 애플리케이션 링크를 제공합니다.

ADK를 사용하는 애플리케이션은 멀티모달 프롬프트와 대답을 수집할 수도 있습니다. 이 문서에서는 텍스트 프롬프트와 대답을 수집하는 방법을 설명합니다. 멀티모달 데이터를 수집하려면 추가 구성이 필요합니다. 자세한 내용은 멀티모달 프롬프트 및 대답 수집 및 보기를 참고하세요.

ADK에서 제공하는 기본 관측 가능성만으로는 애플리케이션의 사용 사례에 충분하지 않을 수 있습니다. OpenTelemetry를 사용하여 애플리케이션의 다른 구성요소에서 원격 분석을 수집하도록 추가 계측 라이브러리를 적용할 수 있습니다. 또는 직접 커스텀 계측을 추가하여, 애플리케이션에 특화된 데이터를 수집함으로써 보다 세밀한 관측을 확보할 수도 있습니다. 예를 들어 애플리케이션에서 다음과 같은 계측 코드를 작성할 수 있습니다.

에이전트가 호출하는 도구의 리소스 소비를 추적합니다.
애플리케이션별 유효성 검사 실패, 비즈니스 규칙 위반, 커스텀 오류 복구 메커니즘을 추적합니다.
도메인별 기준에 따라 에이전트 대답의 품질 점수를 추적합니다.

생성형 AI 애플리케이션을 계측하여 원격 분석 수집

AI 에이전트에서 로그, 측정항목, trace 데이터를 수집할 수 있도록 계측하려면 다음을 수행합니다.

OpenTelemetry 패키지를 설치합니다.
ADK 환경을 구성합니다.

이 섹션의 나머지 부분에서는 위 단계에 대하여 자세히 설명합니다.

OpenTelemetry 패키지 설치

다음 OpenTelemetry 계측 및 내보내기 도구 패키지를 추가합니다.

pip install 'google-adk>=1.17.0' \
  'opentelemetry-instrumentation-google-genai>=0.4b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

로그 및 측정항목 데이터는 Cloud Logging API 또는 Cloud Monitoring API를 사용하여 Google Cloud 프로젝트로 전송됩니다. opentelemetry-exporter-gcp-logging 및 opentelemetry-exporter-gcp-monitoring 라이브러리는 이러한 API의 엔드포인트를 호출합니다.

trace 데이터는 OpenTelemetry OTLP 프로토콜을 구현한 원격 분석(OTLP) API를 통해 Google Cloud 로 전송됩니다. opentelemetry-exporter-otlp-proto-grpc 라이브러리는 원격 분석(OTLP) API 엔드포인트를 호출합니다.

trace 데이터는 일반적으로 OpenTelemetry OTLP 프로토콜에서 정의한 proto 파일과 일치하는 형식으로 저장됩니다. 하지만 일부 필드는 저장 전에 OpenTelemetry 전용 데이터 유형에서 JSON 데이터 유형으로 변환될 수 있습니다. 스토리지 형식에 대한 자세한 내용은 trace 데이터 스키마를 참고하세요.

ADK 환경 구성

ADK 프레임워크 버전 1.17.0 이상에는 OpenTelemetry 지원이 내장되어 있으며 OpenTelemetry 원격 분석 데이터를Google Cloud Observability로 전송할 수 있습니다. 이를 사용 설정하려면 ADK 환경을 구성하세요.

adk web CLI 명령어로 애플리케이션을 실행할 때 --otel_to_cloud 플래그를 포함합니다.

opentelemetry.env 파일에서 다음 환경 변수를 설정합니다.

OTEL_SERVICE_NAME=adk-sql-agent
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

opentelemetry.env 파일에 다음 환경 변수도 추가하는 것이 좋습니다.
```
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false
```
이 환경 변수는 다음을 실행합니다.
- ADK 계측이 속성 크기 제한을 초과하는 스팬 속성을 연결하지 못하도록 방지합니다.
- 개인 식별 정보(PII)가 속성으로 스팬에 연결되지 않도록 합니다.

샘플 애플리케이션 다운로드 및 실행

이 샘플 코드는 ADK를 사용하여 빌드된 생성형 AI 에이전트를 구현합니다. 이 에이전트는 OpenTelemetry로 계측되어 있으며, 측정항목, trace, 로그 데이터를 사용자의 Google Cloud 프로젝트로 전송하도록 구성되어 있습니다. 프로젝트로 전송되는 원격 분석에는 생성형 AI의 프롬프트와 대답이 포함됩니다.

ADK 에이전트 페르소나

이 생성형 AI 에이전트는 임시 SQLite 데이터베이스에 대한 전체 액세스 권한을 가진 SQL 전문가로 정의되어 있습니다. 에이전트는 에이전트 개발 키트를 기반으로 빌드되었으며 SQLDatabaseToolkit을 사용해 데이터베이스에 액세스합니다. 데이터베이스는 초기 상태에서는 비어 있습니다.

시작하기 전에

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable aiplatform.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Install the Google Cloud CLI.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

gcloud CLI를 초기화하려면, 다음 명령어를 실행합니다.

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable aiplatform.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Cloud Shell, Google Cloud리소스 또는 로컬 개발 환경에서 샘플을 실행하는 경우 이 섹션에 나열된 권한으로 충분합니다. 프로덕션 애플리케이션의 경우 일반적으로 서비스 계정이 로그, 측정항목, trace 데이터를 작성하는 사용자 인증 정보를 제공합니다.

샘플 애플리케이션에서 로그, 측정항목, trace 데이터를 작성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
- Cloud 원격 분석 trace 작성자(roles/telemetry.tracesWriter)
- 로그 작성자(roles/logging.logWriter)
- 모니터링 측정항목 작성자(roles/monitoring.metricWriter)
- Vertex AI 사용자(roles/aiplatform.user)

애플리케이션 실행

샘플 애플리케이션을 실행하려면 다음을 수행합니다.

Cloud Shell에서 다음 명령어를 실행합니다.

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git

샘플 디렉터리로 이동합니다.

cd opentelemetry-operations-python/samples/adk-sql-agent

가상 환경을 만들고 샘플을 실행합니다.

python -m venv venv/
source venv/bin/activate
pip install -r requirements.txt
env $(cat opentelemetry.env | xargs) adk web --otel_to_cloud

애플리케이션에 다음과 유사한 메시지가 표시됩니다.

Appplication startup complete
Uvicorn running on http://0.0.0.0:8080

에이전트와 상호작용하려면 이전 단계의 출력에 표시된 URL을 선택합니다.
에이전트 선택을 확장하고 에이전트 목록에서 sql_agent를 선택합니다.

에이전트와 상호작용

에이전트와 상호작용하려면 질문을 하거나 명령을 내리세요. 예를 들어 다음과 같이 질문할 수 있습니다.

What can you do for me ?

마찬가지로, sql_agent는 SQL 전문가 역할을 가지고 있으므로, 애플리케이션용 테이블을 생성하거나, 생성된 테이블에서 작동하는 쿼리를 작성하도록 요청할 수도 있습니다. 에이전트는 애플리케이션이 실행되는 머신에 생성되는 .db 파일 기반의 임시 데이터베이스만 만들 수 있습니다.

다음은 sql_agent와 사용자 간의 샘플 상호작용을 보여줍니다.

sql_agent와의 상호작용을 표시합니다.

생성형 AI 에이전트가 수행하는 작업은 확정적이지 않으므로 동일한 프롬프트에 다른 대답이 표시될 수 있습니다.

애플리케이션 종료

애플리케이션을 종료하려면 애플리케이션을 실행하는 데 사용된 셸에 Ctrl-C를 입력합니다.

trace, 측정항목, 로그 보기

이 섹션에서는 생성형 AI 이벤트를 보는 방법을 설명합니다.

시작하기 전에

로그, 측정항목, trace 데이터를 보는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

로그 뷰어(roles/logging.viewer)
모니터링 뷰어(roles/monitoring.viewer)
Cloud Trace 사용자(roles/cloudtrace.user)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참고하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

원격 분석 보기

애플리케이션으로 생성된 생성형 AI 이벤트를 보려면 Trace 탐색기 페이지를 사용합니다.

Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.
Trace 탐색기로 이동

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.
툴바에서 필터 추가를 선택하고 스팬 이름을 선택한 다음 call_llm를 선택합니다.

다음은 데이터를 필터링한 후의 Trace 탐색기 페이지를 보여줍니다.

Cloud Trace를 사용한 적이 없는 경우 Google Cloud Observability에서 trace 데이터를 저장할 데이터베이스를 만들어야 합니다. 데이터베이스를 만드는 데 몇 분 정도 걸릴 수 있으며 이 기간에는 trace 데이터를 볼 수 없습니다.
스팬 및 로그 데이터를 탐색하려면 스팬 테이블에서 스팬을 선택합니다.

세부정보 페이지가 열립니다. 이 페이지에는 연결된 trace와 그 스팬이 표시됩니다. 페이지의 테이블에는 선택한 스팬에 대한 세부정보가 표시됩니다. 이 정보에는 다음이 포함됩니다.
- 입력/출력 탭에는 생성형 AI 에이전트의 이벤트가 표시됩니다. 이러한 이벤트에 대해 자세히 알아보려면 생성형 AI 이벤트 보기를 참고하세요.
  
  다음 스크린샷은 하나의 스팬에 call_llm라는 이름이 있는 trace를 보여줍니다. 이 범위는 이 에이전트를 지원하는 LLM(대규모 언어 모델)을 호출합니다. 이 샘플에서는 Gemini입니다. Gemini 스팬에는 생성형 AI 이벤트가 포함됩니다.
- 로그 및 이벤트 탭에는 스팬과 연결된 로그 항목과 이벤트가 나열됩니다. 로그 탐색기에서 로그 데이터를 보려면 이 탭의 툴바에서 로그 보기를 선택합니다.
  
  로그 데이터에는 sql_agent의 대답이 포함됩니다. 예를 들어 샘플 실행의 경우 JSON 페이로드에는 다음 콘텐츠가 포함됩니다.
```
{
  "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
  "jsonPayload": {
    "content": {
      "parts": [
        0: {
          "text": "Now I can create the table."
        }
        1: {1}
        ],
      "role": "model"
    }
  },
  ...
}
```

샘플은 측정항목 데이터를 Google Cloud 프로젝트로 전송하도록 계측되어 있지만 측정항목을 생성하지는 않습니다.

OpenTelemetry를 사용하여 ADK 애플리케이션 계측 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

생성형 AI 애플리케이션을 계측하여 원격 분석 수집

OpenTelemetry 패키지 설치

ADK 환경 구성

샘플 애플리케이션 다운로드 및 실행

ADK 에이전트 페르소나

시작하기 전에

애플리케이션 실행

에이전트와 상호작용

애플리케이션 종료

trace, 측정항목, 로그 보기

시작하기 전에

원격 분석 보기

OpenTelemetry를 사용하여 ADK 애플리케이션 계측