이 페이지에서는 기본 제공 측정항목, 맞춤 측정항목, 알림을 사용하여 Vertex AI Agent Engine에서 에이전트를 모니터링하는 방법을 설명합니다.
개요
추가 설정이나 구성 없이 Cloud Monitoring을 사용하여 Vertex AI Agent Engine을 사용할 수 있습니다. 기본 제공 에이전트 측정항목은Google Cloud 콘솔의 Cloud Monitoring 페이지에서 자동으로 수집되고 시각화됩니다.
지원되는 기본 제공 측정항목
다음 에이전트 측정항목이 지원되며 Vertex AI Agent Engine 모니터링 리소스 aiplatform.googleapis.com/ReasoningEngine와 연결됩니다.
- 요청 수
- 요청 지연 시간
- 컨테이너 CPU 할당 시간
- 컨테이너 메모리 할당 시간
측정항목 유형, 단위, 라벨, 지연 시간, 샘플링 기간에 대한 자세한 내용은 AI Platform 측정항목 전체 목록을 참고하세요.
에이전트의 측정항목 보기
Google Cloud 콘솔에서 측정항목 탐색기를 사용하여 에이전트 내장 측정항목을 볼 수 있습니다.
측정항목 탐색기에서 측정항목을 볼 수 있는 권한을 얻으려면 관리자에게 프로젝트에 대한 Monitoring 뷰어 역할(
roles/monitoring.viewer)을 부여해 달라고 요청하세요.Google Cloud 콘솔에서 측정항목 탐색기로 이동합니다.
Google Cloud 프로젝트를 선택합니다.
측정항목 선택을 클릭하여 검색창을 엽니다.
검색창에 Vertex AI Reasoning Engine을 입력하고 Vertex AI Reasoning Engine을 클릭합니다.
Reasoning_engine 측정항목 카테고리를 클릭한 다음 Request count와 같은 측정항목을 클릭합니다.
원하는 경우 추가 라벨 필터, 집계 요소를 설정하고 기간을 조정합니다.
기본적으로 요청 수 측정항목의 측정항목 탐색기 차트는 데이터 포인트를 기본 시간 간격에 맞춰 정렬하고 데이터 포인트를 초당 요청 수 (비율 측정항목)로 표시합니다.
에이전트의 측정항목 쿼리
Prometheus 쿼리 언어 (PromQL) 또는 Cloud Monitoring v3 API를 통해 측정항목을 쿼리할 수도 있습니다. PromQL은 측정항목 필터링, 집계, 변환을 위한 더 많은 옵션을 제공하는 반면 Cloud Monitoring API를 사용하면 모든 원시 데이터 포인트를 프로그래매틱 방식으로 나열하고 쿼리할 수 있습니다.
PromQL로 측정항목 쿼리
PromQL을 사용하여 맞춤 시간 간격으로 데이터 포인트를 정렬하고 집계하고 변환된 데이터 포인트를 초당 요청 수 대신 절대 요청 수로 표시할 수 있습니다. 다음 예에서는 에이전트 엔진 인스턴스 ID (RESOURCE_ID)와 응답 코드(RESPONSE_CODE)를 기준으로 데이터를 필터링합니다.
sum_over_time(
increase(
aiplatform_googleapis_com:reasoning_engine_request_count{
monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
reasoning_engine_id='RESOURCE_ID',
response_code='RESPONSE_CODE'
}
[10m]
)
[10m:10m]
)
특정 오류 응답 코드 (예: 500)로 라벨이 지정된 요청의 비율을 총 요청 수로 계산하여 오류율을 쿼리할 수 있습니다 (실패한 요청의 비율).
sum_over_time(
sum(
rate(
aiplatform_googleapis_com:reasoning_engine_request_count{
monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
reasoning_engine_id='RESOURCE_ID',
response_code='500'
}
[10m]
)
)
[10m:10m]
)
/
sum_over_time(
sum(
rate(
aiplatform_googleapis_com:reasoning_engine_request_count{
monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
reasoning_engine_id='RESOURCE_ID',
}
[10m]
)
)
[10m:10m]
)
비율 측정항목의 권장사항 및 제한사항은 측정항목 비율 정보를 참고하세요. 오류율 측정항목에 대한 알림을 설정하는 방법의 예는 JSON의 샘플 정책을 참고하세요.
Cloud Monitoring API로 측정항목 쿼리
Cloud Monitoring API를 사용하여 다음 작업을 할 수 있습니다.
Vertex AI Agent Engine 모니터링 리소스 정의 가져오기
사용 가능한 에이전트 측정항목 정의 나열
request_count의 시계열 데이터 쿼리
모든 에이전트 측정항목은 에이전트 엔진 모니터링 리소스 aiplatform.googleapis.com/ReasoningEngine와 연결됩니다.
API 탐색기, 언어별 클라이언트 라이브러리 또는 명령줄을 통해 이러한 API를 호출할 수 있습니다. API 탐색기 및 클라이언트 라이브러리를 통해 측정항목을 읽는 방법은 문서를 참고하세요. 다음 예시에서는 명령줄, 특히 curl 도구의 사용법을 보여줍니다.
Agent Engine 모니터링 리소스 정의 가져오기
다음 명령어는 projects.monitoredResourceDescriptors를 사용하여 모니터링 리소스의 정의와 필터링에 사용할 수 있는 모든 사용 가능한 라벨을 가져옵니다.
gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/monitoredResourceDescriptors/aiplatform.googleapis.com/ReasoningEngine
라벨에는 resource_container, location, reasoning_engine_id가 포함되어야 합니다.
사용 가능한 에이전트 측정항목 정의 나열
다음 명령어는 projects.metricDescriptors를 사용하여 Agent Engine의 모든 측정항목과 라벨 필터를 가져옵니다.
gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/metricDescriptors?filter='metric.type=starts_with("aiplatform.googleapis.com/reasoning_engine")'결과에는 다음 측정항목의 정의와 특정 라벨이 포함되어야 합니다.
aiplatform.googleapis.com/reasoning_engine/request_countaiplatform.googleapis.com/reasoning_engine/request_latenciesaiplatform.googleapis.com/reasoning_engine/cpu/allocation_timeaiplatform.googleapis.com/reasoning_engine/memory/allocation_time
request_count의 시계열 데이터 쿼리
interval, filter, aggregation과 같은 매개변수와 함께 projects.timeSeries.list를 사용하여 시계열 데이터를 쿼리할 수 있습니다.
다음 예에서는 특정 기간 동안 특정 에이전트 인스턴스의 request_count 측정항목의 원시 데이터 포인트를 쿼리하는 방법을 보여줍니다.
gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/timeSeries?filter='metric.type="aiplatform.googleapis.com/reasoning_engine/request_count"%20AND%20resource.labels.reasoning_engine_id="RESOURCE_ID"&interval.endTime=2025-03-26T11:00:0.0-08:00&interval.startTime=2025-03-26T10:00:0.0-08:00'
다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID입니다.
- RESOURCE_ID: Agent Engine 인스턴스 ID입니다. 항상 필요한 것은 아닙니다. 동일한 프로젝트 내에서 여러 Agent Engine 인스턴스를 쿼리할 수 있습니다.
interval.startTime및interval.endTime: RFC 3339 형식의 시간 간격 시작 (포함) 및 종료(제외)입니다. 예를 들어 협정 세계시 (UTC)는"2025-03-26T11:22:33Z", 태평양 표준시 (PST)는"2025-03-26T11:22:33-08:00"입니다. 전체 정의와 추가 예는 RFC 3339를 참고하세요.
다음과 비슷한 응답이 표시됩니다.
{
"timeSeries": [
{
"metric": {
"labels": {
"response_code": "200",
"response_code_class": "2xx"
},
"type": "aiplatform.googleapis.com/reasoning_engine/request_count"
},
"resource": {
"type": "aiplatform.googleapis.com/ReasoningEngine",
"labels": {
"reasoning_engine_id": "RESOURCE_ID",
"location": "LOCATION",
"project_id": "PROJECT_ID"
}
},
"metricKind": "DELTA",
"valueType": "INT64",
"points": [
{
"interval": {
"startTime": "2025-03-26T18:55:27.001Z",
"endTime": "2025-03-26T18:56:27Z"
},
"value": {
"int64Value": "25"
}
},
{
"interval": {
"startTime": "2025-03-26T18:54:27.001Z",
"endTime": "2025-03-26T18:55:27Z"
},
"value": {
"int64Value": "36"
}
}
// ... more data points ...
]
}
// ... potentially more time series with other response codes ...
],
"unit": "1"
}
대답 형식에 관한 자세한 내용은 projects.timeSeries.list을 참고하세요.
에이전트의 맞춤 측정항목 만들기
기본 제공 에이전트 측정항목이 특정 사용 사례를 다루지 않는 경우 맞춤 측정항목을 정의할 수 있습니다. 다음 방법을 사용하여 맞춤 측정항목을 만들 수 있습니다.
로그 기반 측정항목: 대규모 로그 항목에서 트렌드 및 패턴을 관찰합니다.
사용자 정의 측정항목: 애플리케이션별 데이터 또는 클라이언트 측 시스템 데이터를 캡처하는 등 Google Cloud에서 정의되지 않은 측정항목입니다.
로그 기반 측정항목
다음 단계에서는 여러 에이전트가 여러 도구를 호출하고 도구 호출을 집계하려는 예시 워크플로에 대해 로그 기반 측정항목 (tool_calling_count)을 만들고 사용하는 방법을 보여줍니다.
호출될 때마다 로그 항목을 작성하도록 도구를 지정합니다. 예를 들면
"tool-\<tool-id\> invoked by agent-\<agent-id\>"입니다.Google Cloud 콘솔을 통해 새 카운터 유형 로그 기반 측정항목을 만듭니다.
Google Cloud 콘솔에서 로그 기반 측정항목 페이지로 이동합니다.
사용자 정의 측정항목 섹션에서 측정항목 만들기를 클릭합니다. 로그 기반 측정항목 만들기 창이 표시됩니다.
측정항목 유형에서 카운터를 선택합니다.
세부정보 섹션에 로그 기반 측정항목 이름을 입력합니다. 예를 들면
tool_calling_count입니다. 원하는 경우 설명과 단위를 입력합니다.필터 선택 섹션에서 다음을 수행합니다.
프로젝트 또는 로그 버킷 선택 드롭다운 목록에서 프로젝트 로그를 선택합니다.
필터 빌드 필드에 로깅 쿼리 언어를 사용하여 로그 필터를 입력합니다. 예를 들면 다음과 같습니다.
resource.type="aiplatform.googleapis.com/ReasoningEngine" resource.labels.reasoning_engine_id="RESOURCE_ID" textPayload =~ "tool-\d+ invoked by agent-\d+" -- assuming both tool and agent IDs are numeric
라벨 섹션에서 라벨 추가 버튼을 클릭하여 새 라벨 두 개를 추가합니다.
첫 번째 라벨의 경우 다음을 수행합니다.
라벨 이름 필드에
tool를 입력합니다.필드 이름 필드에
textPayload를 입력합니다.정규 표현식 필드에
(tool-\d+) invoked by agent-\d+을 입력합니다.
두 번째 라벨의 경우 다음을 수행합니다.
라벨 이름 필드에
agent를 입력합니다.필드 이름 필드에
textPayload를 입력합니다.정규 표현식 필드에
tool-\d+ invoked by (agent-\d+)을 입력합니다.
- 완료를 클릭합니다.
측정항목 만들기를 클릭합니다.
tool_calling_count측정항목 및 관련 로그를 보려면 Google Cloud 콘솔에서 다음 단계를 따르세요.Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.
측정항목 선택을 클릭하여 검색창을 엽니다.
검색창에 Vertex AI Reasoning Engine을 입력하고 Vertex AI Reasoning Engine을 클릭합니다.
로그 기반 측정항목 측정항목 카테고리를 클릭한 다음 Logging/user/tool_calling_count를 클릭합니다. 필요한 경우 시간 범위를 조정합니다.
(선택사항)
tool및agent라벨로 필터링합니다.모든 상담사의 특정 도구에 대한 총 호출 수를 가져오려면 해당 도구 ID 값으로 필터 라벨
tool를 설정합니다.모든 도구에 대해 특정 에이전트의 총 호출 수를 가져오려면 해당 에이전트 ID 값으로 필터 라벨
agent를 설정합니다.
원하는 경우 합계 기준을
tool또는agent로 설정하여 여러 도구 또는 상담사별 총계를 확인할 수 있습니다.
에이전트 로그를 작성하는 방법은 에이전트 로깅을, 로그 기반 측정항목에 대한 자세한 내용은 로그 기반 측정항목 개요를 참고하세요.
사용자 정의 측정항목
다음 단계에서는 여러 에이전트가 여러 모델을 호출하는 워크플로의 사용자 정의 측정항목(token_count)을 만들고 사용하는 방법을 보여줍니다. 여기서는 호출하는 각 에이전트와 타겟 모델에 대해 애플리케이션 시작 이후의 토큰 수를 추적한다고 가정하고 소비된 토큰의 총수를 계산하려고 합니다.
다음 매개변수를 사용하여
projects.metricDescriptors.create를 호출하여 맞춤 측정항목 유형을 정의합니다.name: URL 문자열(예:projects/PROJECT_ID)Request body:MetricDescriptor객체:{ "name": "token_count", "description": "Token Consumed by models.", "displayName": "Token Count", "type": "custom.googleapis.com/token_count", "metricKind": "CUMULATIVE", "valueType": "INT64", "unit": "1", "labels": [ { "key": "model", "valueType": "STRING", "description": "Model." }, { "key": "agent", "valueType": "STRING", "description": "Agent." } ], "monitoredResourceTypes": [ "generic_node" ] }새 측정항목
token_count이(가) 애플리케이션 시작 이후의 총 토큰 수를 나타내는 종류Cumulative로 생성됩니다.Cumulative측정항목에 대한 자세한 내용은 측정항목 종류 및 유형을 참고하세요.model및agent라벨은 타겟 대규모 언어 모델 (LLM)과 호출 에이전트의 이름을 나타냅니다.
token_count측정항목은 측정항목 탐색기에서 확인할 수 있습니다.- Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.
측정항목 선택을 클릭하여 검색창을 엽니다.
검색창에 일반 노드를 입력하고 맞춤 측정항목을 클릭합니다.
토큰 수를 클릭합니다.
다음 매개변수를 사용하여
projects.timeSeries.create를 호출하여 새 측정항목에 데이터 포인트를 씁니다.name: URL 문자열(예:projects/PROJECT_ID)Request body:TimeSeries객체 목록입니다.{ "timeSeries": [ { "metric": { "type": "custom.googleapis.com/token_count", "labels": { "model": "model-1", "agent": "agent-1" } }, "resource": { "type": "generic_node", "labels": { "project_id": "PROJECT_ID", "node_id": "RESOURCE_ID", "namespace": "", "location": "us-central1" } }, "points": [ { "interval": { "startTime": "2025-03-26T10:00:00-08:00", "endTime": "2025-03-26T10:01:00-08:00" }, "value": { "int64Value": 15 } } ] }, { "metric": { "type": "custom.googleapis.com/token_count", "labels": { "model": "model-1", "agent": "agent-2" } }, "resource": { "type": "generic_node", "labels": { "project_id": "PROJECT_ID", "node_id": "RESOURCE_ID", "namespace": "", "location": "us-central1" } }, "points": [ { "interval": { "startTime": "2025-03-26T10:00:00-08:00", "endTime": "2025-03-26T10:01:00-08:00" }, "value": { "int64Value": 20 } } ] } // ... more time series ... ] }
Cloud Monitoring API를 통해 데이터 포인트를 업로드하면 Google Cloud 콘솔을 통해 새 측정항목
token_count을 볼 수 있습니다.Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.
측정항목 선택을 클릭하여 검색창을 엽니다.
검색창에 일반 노드를 입력하고 맞춤 측정항목을 클릭합니다.
토큰 수를 클릭합니다. 필요한 경우 시간 범위를 조정하고
model또는agent의 라벨 값을 구성합니다.
에이전트 알림 만들기
측정항목을 알림과 함께 사용할 수 있습니다. 자세한 내용은 알림 개요를 참고하세요.
다음 예에서는 지정된 기간 동안 지연 시간이 사전 정의된 값을 초과할 때 알림을 받을 수 있도록 request_latencies 측정항목에 대한 기준점 알림을 만드는 방법을 보여줍니다.
Google Cloud 콘솔에서 알림 페이지로 이동합니다.
정책 만들기를 클릭합니다. 알림 정책 만들기 페이지가 열립니다.
정책 구성 모드에서 빌더를 선택합니다.
측정항목 선택 드롭다운 메뉴에서
Vertex AI Reasoning Engine->reasoning_engine->Request Latency를 선택합니다.필터 추가 섹션에서 필요에 따라 필터 (예:
reasoning_engine_id,response_code)를 구성합니다.데이터 변환 섹션에서 순환 기간 및 순환 기간 함수를
5min및99th percentile와 같은 값으로 전환합니다 (5분 정렬 기간 동안 요청 지연 시간의 99번째 백분위수 모니터링).다음을 클릭합니다.
알림 트리거 구성 섹션에서 다음을 수행합니다.
조건 유형으로 기준점을 선택합니다.
알림 트리거(예: 모든 시계열 위반)을 선택합니다.
기준 위치(예: 기준 초과)를 선택합니다.
기준 값(예:
5000ms)을 입력합니다.다음을 클릭합니다.
알림 구성 및 알림 완료 섹션에서 다음을 수행합니다.
알림 채널을 하나 이상 선택합니다. 자세한 내용은 알림 채널 관리를 참고하세요.
(선택사항) 알림 제목, 이슈 자동 종료 기간, 애플리케이션 라벨, 정책 라벨, 심각도 수준, 추가 문서를 구성합니다.
알림 정책 이름 지정 섹션에서 정책 이름을 설정합니다(예:
latency-99p-alert).정책 만들기를 클릭합니다.
문제가 발생한 경우 측정항목 기반 알림 정책의 문제에서 문제 확인 및 조사, 알림 음소거에 대한 자세한 내용을 확인하세요.
JSON의 샘플 정책에서 알림 예시를 더 확인할 수 있습니다.
에이전트의 측정항목 모니터링
Vertex AI Agent Engine 개요 대시보드를 사용하여 에이전트의 운영 상태와 성능을 모니터링할 수 있습니다.
기본 대시보드 보기
Google Cloud 콘솔의 대시보드 페이지로 이동합니다.
Google Cloud 프로젝트를 선택합니다.
내 대시보드 창에서
Name:Vertex AI Agent Engine Overview필터를 추가합니다.Vertex AI Agent Engine 개요를 클릭하여 기본 에이전트 대시보드를 표시합니다.
기본 대시보드 맞춤설정
기본 대시보드에는 에이전트 기본 제공 측정항목만 포함됩니다. 대시보드에 자체 맞춤 측정항목을 추가하려면 다음 단계에 따라 기본 대시보드를 복사하고 맞춤설정하세요.
대시보드 복사를 클릭합니다. 대시보드 복사 대화상자에서 복사를 클릭합니다. 대시보드 사본이 열립니다. 맞춤 카테고리의 내 대시보드 창에서도 대시보드 사본을 찾을 수 있습니다.
대시보드 사본에서 다음 단계에 따라 측정항목을 추가합니다.
위젯 추가를 클릭합니다. 위젯 추가 측면 패널이 표시됩니다.
데이터에서 측정항목을 선택합니다. 위젯 구성 측면 패널이 표시됩니다.
측정항목 선택을 클릭하여 검색창을 엽니다.
로그 기반 측정항목을 사용하여 커스텀 측정항목을 만든 경우:
검색창에 Vertex AI Reasoning Engine을 입력하고 Vertex AI Reasoning Engine을 클릭합니다.
로그 기반 측정항목 측정항목 카테고리를 클릭한 다음 Logging/user/tool_calling_count와 같은 측정항목을 클릭합니다.
적용을 클릭합니다.
사용자 정의 측정항목을 사용하여 맞춤 측정항목을 만든 경우:
검색창에 일반 노드를 입력하고 일반 노드를 클릭합니다.
맞춤 측정항목 측정항목 카테고리를 클릭한 다음 토큰 수와 같은 측정항목을 클릭합니다.
적용을 클릭합니다.
맞춤 측정항목을 표시하는 새 차트가 대시보드에 표시됩니다.
다음과 같이 대시보드의 레이아웃을 추가로 조정할 수 있습니다.
위젯 제목을 길게 누른 다음 동일한 대시보드의 다른 위치로 드래그하여 위젯을 이동합니다.
위젯 오른쪽 하단 모서리를 길게 누른 다음 크기를 조정하여 위젯 크기를 조절합니다.
Prometheus 쿼리 언어 (PromQL)를 사용하여 측정항목 차트를 추가하고 측정항목을 표로 만드는 방법에 관한 자세한 내용은 커스텀 대시보드에 차트 및 표 추가를 참고하세요.
맞춤 알림을 구성한 경우 대시보드에 알림 정책 및 알림 표시를 참고하여 대시보드에 알림을 추가하세요.