이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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

이 문서에서는 에이전트 개발 키트 (ADK) 프레임워크로 빌드된 AI 에이전트를 계측하는 방법을 설명합니다. OpenTelemetry를 활용하는 이 계측을 사용하면 사용자 프롬프트, 에이전트 응답, 에이전트 선택사항을 수집할 수 있습니다.

ADK 프레임워크는 에이전트 실행의 주요 단계에서 원격 분석을 캡처하는 OpenTelemetry로 계측됩니다. 이를 통해 기본적으로 유용한 애플리케이션 모니터링 가능성을 제공합니다. 하지만 이 관측 가능성이 애플리케이션의 사용 사례에 충분하지 않을 수 있습니다. OpenTelemetry를 사용하여 앱의 다른 부분에서 원격 분석을 캡처하거나 자체 맞춤 계측을 사용하여 애플리케이션별 데이터를 캡처하여 더 세부적인 관측 가능성을 확보함으로써 추가 계측 라이브러리를 추가할 수 있습니다.

예를 들어 애플리케이션에서 다음 작업을 실행하는 계측 코드를 작성할 수 있습니다.

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

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

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

OpenTelemetry 패키지 설치
원격 분석을 수집하고 전송하도록 OpenTelemetry 구성
구성된 OpenTelemetry를 삽입하는 맞춤 진입점 작성

이 섹션의 나머지 부분에서는 이전 단계를 설명합니다.

OpenTelemetry 패키지 설치

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

pip install 'opentelemetry-instrumentation-google-genai' \
  '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 데이터는 OTLP 형식을 지원하는 Telemetry (OTLP) API를 사용하여 Google Cloud 로 전송됩니다. 이 엔드포인트를 통해 수신된 데이터도 OTLP 형식으로 저장됩니다. opentelemetry-exporter-otlp-proto-grpc 라이브러리는 Telemetry (OTLP) API 엔드포인트를 호출합니다.

원격 분석을 수집하고 전송하도록 OpenTelemetry 구성

ADK 에이전트의 초기화 코드에서 OpenTelemetry를 구성하여 원격 분석을 캡처하고 Google Cloud 프로젝트로 전송하는 코드를 추가합니다.

전체 샘플을 보려면 더보기를 클릭한 다음 GitHub에서 보기를 선택합니다.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "adk-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    # ADK uses Vertex AI and Google Gen AI SDKs.
    VertexAIInstrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

구성된 OpenTelemetry를 사용하는 맞춤 진입점 작성

계측에 OpenTelemetry를 사용하려면 ADK 애플리케이션의 맞춤 진입점을 만드세요. 맞춤 진입점은 ADK 에이전트를 실행하기 전에 OpenTelemetry를 구성해야 합니다.

샘플 애플리케이션에서 main 메서드는 OpenTelemetry를 초기화한 다음 에이전트와 상호작용할 수 있는 FastAPI 서버를 실행하는 맞춤 진입점으로 작동합니다.

전체 샘플을 보려면 더보기를 클릭한 다음 GitHub에서 보기를 선택합니다.

def main() -> None:
    # Make sure to set:
    # OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
    # in order to full prompts and responses and logs messages.
    # For this sample, these can be set by loading the `opentelemetry.env` file.
    setup_opentelemetry()

    # Call the function to get the FastAPI app instance.
    # Ensure that the agent director name is the name of directory containing agent subdirectories,
    # where each subdirectory represents a single agent with __init__.py and agent.py files.
    # For this example this would be the current directory containing main.py.
    # Note: Calling this method attempts to set the global tracer provider, which has already been
    # set by the setup_opentelemetry() function.
    app = get_fast_api_app(
        agents_dir=AGENT_DIR,
        session_service_uri=SESSION_DB_URL,
        allow_origins=ALLOWED_ORIGINS,
        web=SERVE_WEB_INTERFACE,
    )

    # Lauch the web interface on port 8080.
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

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

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

ADK 에이전트 페르소나

생성형 AI 에이전트는 임시 SQLite 데이터베이스에 대한 전체 액세스 권한이 있는 SQL 전문가로 정의됩니다. 에이전트는 에이전트 개발 키트로 빌드되며 SQLDatabaseToolkit을 사용하여 데이터베이스에 액세스합니다. 데이터베이스는 처음에는 비어 있습니다.

시작하기 전에

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
Enable the APIs
샘플 애플리케이션에서 로그, 측정항목, trace 데이터를 작성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
- Cloud 원격 분석 trace 작성자(roles/telemetry.tracesWriter)
- 로그 작성자(roles/logging.logWriter)
- 모니터링 측정항목 작성자(roles/monitoring.metricWriter)
- Vertex AI 사용자(roles/aiplatform.user)

애플리케이션 실행

샘플 애플리케이션을 실행하려면 다음 단계를 따르세요.

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

저장소를 복제합니다.

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) python main.py

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

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

에이전트와 상호작용하려면 이전 단계에 나열된 주소로 브라우저를 엽니다.
상담사 선택을 펼치고 상담사 목록에서 sql_agent을 선택합니다.

에이전트와 상호작용

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

What can you do for me ?

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

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

Create a table for me to store weather data and also insert sample data in
the table. At the end show all data in the table you created.

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 에이전트의 이벤트가 표시됩니다. 이러한 이벤트에 대해 자세히 알아보려면 생성형 AI 이벤트 보기를 참조하세요.
  
  다음 스크린샷은 하나의 스팬에 call_llm라는 이름이 있는 trace를 보여줍니다. 이 범위는 이 에이전트를 지원하는 LLM (대규모 언어 모델)을 호출합니다. 이 샘플에서는 Gemini입니다. Gemini 스팬에는 생성형 AI 이벤트가 포함됩니다.
- 로그 및 이벤트 탭에는 스팬과 연결된 로그 항목과 이벤트가 나열됩니다. 로그 탐색기에서 로그 데이터를 보려면 이 탭의 툴바에서 로그 보기를 선택합니다.
  
  로그 데이터에는 sql_agent의 응답이 포함됩니다. 예를 들어 샘플 실행의 경우 JSON 페이로드에는 다음 콘텐츠가 포함됩니다.
```
{
  "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
  "jsonPayload": {
    "content": {
      "role": "model",
      "parts": [
        {
          "executable_code": null,
          "inline_data": null,
          "thought": null,
          "video_metadata": null,
          "code_execution_result": null,
          "function_response": null,
          "thought_signature": null,
          "text": "Okay, I will create a table named `weather` with columns `id`, `city`, `temperature`, and `date`. Then I will insert some sample rows into the table and display all the data in the table.\n",
          "file_data": null,
          "function_call": null
        }
      ]
    }
  },
  ...
}
```

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

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

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

OpenTelemetry 패키지 설치

원격 분석을 수집하고 전송하도록 OpenTelemetry 구성

구성된 OpenTelemetry를 사용하는 맞춤 진입점 작성

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

ADK 에이전트 페르소나

시작하기 전에

애플리케이션 실행

에이전트와 상호작용

애플리케이션 종료

trace, 측정항목, 로그 보기

시작하기 전에

원격 분석 보기

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