로깅 구성

이 문서에서는 다음 작업을 로깅하도록 Model Armor를 구성하는 방법을 설명합니다.

• 템플릿을 생성, 업데이트 또는 삭제하는 작업
• 사용자 프롬프트 또는 모델 응답을 정리하는 작업

Model Armor는 감사 로그를 사용하여 관리 및 리소스 관리 활동을 기록합니다. 자세한 내용은 Model Armor 감사 로깅을 참조하세요.

로그 가격에 대한 자세한 내용은 Cloud Logging 가격 책정을 참고하세요. 처리된 데이터의 양에 따라 Model Armor 사용 요금이 부과될 수도 있습니다. 자세한 내용은 Model Armor 가격 책정을 참고하세요.

시작하기 전에

시작하기 전에 다음 작업을 완료하세요.

필수 권한 얻기

Model Armor의 로깅을 구성하는 데 필요한 권한을 얻으려면 관리자에게 Model Armor 템플릿에 대한 Model Armor 관리자 (roles/modelarmor.admin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

API 사용 설정

Model Armor를 사용하려면 먼저 Model Armor API를 사용 설정해야 합니다.

콘솔

1. Model Armor API를 사용 설정합니다.

   API 사용 설정에 필요한 역할

   API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기

   API 사용 설정하기

2. Model Armor를 활성화할 프로젝트를 선택합니다.

gcloud

시작하기 전에 Model Armor API와 함께 Google Cloud CLI를 사용하여 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

   Cloud Shell 활성화

   Google Cloud 콘솔 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

2. gcloud CLI를 사용하여 API 엔드포인트 재정의를 설정합니다.

gcloud CLI를 사용하여 API 엔드포인트 재정의 설정

이 단계는 gcloud CLI를 사용하여 Model Armor API를 사용 설정하는 경우에만 필요합니다. gcloud CLI가 Model Armor 서비스로 요청을 올바르게 라우팅하도록 API 엔드포인트 재정의를 수동으로 설정해야 합니다.

다음 명령어를 실행하여 Model Armor 서비스의 API 엔드포인트를 설정합니다.

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

LOCATION을 Model Armor를 사용하려는 리전으로 바꿉니다.

트래픽 삭제 설정

Google 및 Google Cloud MCP 서버의 경우 최소 기준 설정을 통해 트래픽 삭제를 설정합니다. 자세한 내용은 Google 및Google Cloud MCP 서버 보호 구성을 참고하세요.

템플릿에서 로깅 구성

템플릿은 다양한 안전 및 보안 카테고리에 대한 필터와 기준점을 정의합니다. Model Armor 템플릿을 만들거나 업데이트할 때 Model Armor가 특정 작업을 로깅할지 여부를 지정할 수 있습니다. 템플릿 메타데이터에서 다음 플래그를 사용합니다.

• log_template_operations: 템플릿 생성, 업데이트, 읽기, 삭제 작업을 로깅할 수 있는 불리언 값입니다.
• log_sanitize_operations: 정리 작업 중에 사용자 프롬프트와 모델 응답의 전체 콘텐츠를 로깅할 수 있는 불리언 값입니다.

콘솔

1. Google Cloud 콘솔에서 Model Armor 페이지로 이동합니다.

   Model Armor로 이동

2. Model Armor를 활성화한 프로젝트가 표시되었는지 확인합니다.

3. Model Armor 페이지에서 템플릿 만들기를 클릭합니다. 템플릿 만들기에 대한 자세한 내용은 Model Armor 템플릿 만들기를 참고하세요.

4. 로깅 구성 섹션에서 로깅을 구성할 작업을 선택합니다.

5. 만들기를 클릭합니다.

REST

  curl -X POST \
      -d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

다음을 바꿉니다.

• PROJECT_ID: 템플릿이 속한 프로젝트의 ID
• LOCATION: 템플릿의 위치
• TEMPLATE_ID: 템플릿의 ID

Python

이 코드를 실행하려면 먼저 Python 개발 환경을 설정하고 Model Armor Python SDK를 설치합니다.

   request = modelarmor_v1.CreateTemplateRequest(
     parent="projects/PROJECT_ID/locations/LOCATION",
     template_id="TEMPLATE_ID",
     template={
        "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "filter_config": {},
        "template_metadata": {
           "log_template_operations": True,
           "log_sanitize_operations": True
        }
     }
   )
   response = client.create_template(request=request)
   

다음을 바꿉니다.

• PROJECT_ID: 템플릿이 속한 프로젝트의 ID
• LOCATION: 템플릿의 위치
• TEMPLATE_ID: 템플릿의 ID

최소 기준 설정에서 로깅 구성

Gemini Enterprise Agent Platform 및 프로젝트 내 Google과 Google Cloud MCP 서버의 Gemini 모델 트래픽에 최소 기준 설정을 적용하면 최소 기준 설정이 정리 작업의 안전 및 보안 필터를 정의합니다. Model Armor 최소 기준 설정을 업데이트할 때 Model Armor가 정리 작업을 로깅할지 여부를 지정할 수 있습니다.

에이전트 플랫폼과 Google 및 Google Cloud MCP 서버의 정리 작업 로깅을 개별적으로 사용 설정할 수 있습니다. 사용 설정하면 로그에 프롬프트와 응답 (Agent Platform의 경우) 또는 도구 호출과 도구 응답(MCP 서버의 경우), Model Armor의 평가 결과, 추가 메타데이터 필드가 포함됩니다.

참고: Google Cloud 콘솔에서 정리 작업의 최소 기준 설정 로깅은 에이전트 플랫폼의 경우 기본적으로 사용 설정되어 있지만 MCP 서버의 경우 기본적으로 사용 중지되어 있습니다.

데이터 레지던시 요구사항이 있는 경우 다음 절차에서 Cloud Logging을 사용 설정하기 전에 규정을 준수하는 저장소 위치로 로그를 라우팅하도록 로그 싱크를 구성해야 합니다. 로그 싱크를 구성하면 Model Armor가 적절한 리전 버킷에 로그를 저장할 수 있습니다. 자세한 내용은 로그 리전화를 참고하세요.

다음 예에서는 에이전트 플랫폼과 Google 및 Google Cloud MCP 서버 모두에 대해 정리 작업 로깅을 사용 설정하는 방법을 보여줍니다.

콘솔

1. Google Cloud 콘솔에서 Model Armor 페이지로 이동합니다.

   Model Armor로 이동

2. Model Armor를 활성화한 프로젝트가 표시되었는지 확인합니다.

3. 최소 기준 설정 탭으로 이동합니다.

4. 로그 섹션에서 Vertex AI 및 Google 관리 MCP 체크박스를 선택하여 각 서비스의 로깅을 사용 설정합니다.

5. 저장을 클릭합니다.

gcloud

--enable-vertex-ai-cloud-logging 플래그를 사용하여 Agent Platform의 로깅을 사용 설정하고 --enable-google-mcp-server-cloud-logging 플래그를 사용하여 Google 및 Google Cloud MCP 서버의 로깅을 사용 설정합니다. 로깅을 사용 중지하려면 --no-enable-vertex-ai-cloud-logging 및 --no-enable-google-mcp-server-cloud-logging 플래그를 사용합니다.

다음 예시 명령어는 에이전트 플랫폼과 Google 및 Google Cloud MCP 서버 모두에 대해 정리 작업 로깅을 사용 설정합니다.

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

PROJECT_ID를 프로젝트의 ID로 바꿉니다.

REST

로깅을 사용 설정하려면 UpdateFloorSetting 메서드에서 Agent Platform의 경우 aiPlatformFloorSetting.enableCloudLogging을 true로, Google 및 Google Cloud MCP 서버의 경우 googleMcpServerFloorSetting.enableCloudLogging을 true로 설정합니다.

다음 예시 명령어는 에이전트 플랫폼과 Google 및 Google Cloud MCP 서버 모두에 대해 정리 작업 로깅을 사용 설정합니다.

curl -X PATCH \
 -d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"

PROJECT_ID를 프로젝트의 ID로 바꿉니다.

Python

이 코드를 실행하려면 먼저 Python 개발 환경을 설정하고 Model Armor Python SDK를 설치합니다.

from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2

# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()

project_id = "PROJECT_ID"
location = "global"

floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"

request = modelarmor_v1.UpdateFloorSettingRequest(
    floor_setting=modelarmor_v1.FloorSetting(
        name=floor_setting_name,
        ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
            enable_cloud_logging=True
        ),
        google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
            enable_cloud_logging=True
        ),
    ),
    update_mask=field_mask_pb2.FieldMask(
        paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
    )
)

try:
    response = client.update_floor_setting(request=request)
    print("Successfully updated floor settings logging.")
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

PROJECT_ID를 프로젝트의 ID로 바꿉니다.

Model Armor 로그 보기 및 필터링

Model Armor 로그를 보고 필터링하려면 Logging의 로그 탐색기를 사용하세요.

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

   로그 탐색기로 이동

   자세한 내용은 로그 탐색기를 사용하여 로그 보기를 참고하세요.

2. 쿼리 창에 다음 쿼리 중 하나를 입력하여 Model Armor 로그를 필터링합니다.

   • 감사 로그 및 삭제 작업 로그를 비롯한 모든 Model Armor 로그를 보려면 다음 단계를 따르세요.

     protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
     

   • Model Armor 감사 로그만 보려면 다음 단계를 따르세요.

     protoPayload.serviceName="modelarmor.googleapis.com"
     

     모든 서비스 이름과 모니터링 리소스 유형의 목록은 모니터링 리소스 및 서비스를 참고하세요.

   • 정리 작업을 위한 Model Armor 로그만 보려면 다음 단계를 따르세요.

     jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
     

     정리 작업 로그를 더 세부적으로 조정하려면 쿼리에서 클라이언트 이름 또는 연관 ID를 지정하면 됩니다.

     • 클라이언트 이름 사용: Model Armor가 Gemini Enterprise Agent Platform 또는 Gemini Enterprise와 같은 서비스와 통합되면 클라이언트 이름을 사용하여 특정 통합의 로그를 필터링할 수 있습니다.

       jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
       labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
       

     • 상관관계 ID 사용:

       jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
       labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
       

     다음을 바꿉니다.

     • CLIENT_NAME: 클라이언트 이름 다음 중 한 가지 값을 사용합니다.
       • CLIENT_NAME_UNSPECIFIED: 클라이언트 이름이 지정되지 않은 경우 사용되는 기본값입니다.
       • VERTEX_AI: Gemini Enterprise Agent Platform과의 통합에 사용됩니다.
       • LOAD_BALANCER: 부하 분산기를 서비스 확장 프로그램으로 사용하여 통합하는 경우
       • LANGCHAIN: LangChain과의 통합
       • GEMINI_ENTERPRISE_BUSINESS: Gemini Enterprise - Business 에디션과의 통합에 사용됩니다.
       • GOOGLE_MCP_SERVER: Google 및 Google 관리형 MCP 서버와의 통합
       • AGENT_GATEWAY: 에이전트 게이트웨이와의 통합
       • GEMINI_ENTERPRISE_NON_BUSINESS Business (Standard, Plus, Frontline) 이외의 Gemini Enterprise 버전과의 통합
       • SECURE_WEB_PROXY Secure Web Proxy와의 통합에 사용됩니다.
     • CORRELATION_ID: 특정 요청에 대해 생성하는 고유 식별자

로그 및 관련 이벤트의 상관관계 파악

특정 상호작용의 로그와 이벤트를 연결하려면 Model Armor 클라이언트 연관 ID를 사용하면 됩니다. 이 ID는 시스템 전반에서 특정 요청을 추적하기 위해 생성하는 고유 식별자 (예: UUID)입니다. curl 헤더에서 클라이언트 연관 ID를 설정하려면 -H 옵션을 사용하여 요청에 MA-Client-Correlation-Id 커스텀 헤더를 포함합니다.

다음은 샘플 형식입니다.

uuid=$(uuidgen) \
curl -X POST -d  '{"userPromptData": { "text": "USER_PROMPT" } }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

curl -X POST \
    -d  '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
    -H "Content-Type: application/json" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"

다음을 바꿉니다.

• PROJECT_ID: 템플릿이 속한 프로젝트의 ID
• LOCATION: 템플릿의 위치
• TEMPLATE_ID: 템플릿의 ID
• USER_PROMPT: 모델에 제공된 프롬프트
• MODEL_RESPONSE: 모델로부터 받은 응답

플랫폼 로그와 Cloud 감사 로그 비교

Model Armor 템플릿 또는 최소 기준 설정 내에서 사용 설정할 수 있는 로그와 Cloud 감사 로그를 구분하는 것이 중요합니다.

기능	Cloud 감사 로그	플랫폼 로그
기본 목적	API 호출 (누가 언제 무엇을 했는지)의 보안 감사 및 규정 준수 모니터링	운영 모니터링, 디버깅, 소독 이벤트의 상세 분석
캡처된 API 작업	템플릿 및 층 설정에 대한 생성, 읽기, 업데이트, 삭제, 나열 작업 삭제 작업 (SanitizeUserPrompt, SanitizeModelResponse)은 메타데이터로 로깅됩니다.	SanitizeUserPrompt 및 SanitizeModelResponse과 같은 모든 요청을 캡처합니다.
페이로드 콘텐츠	정리 작업의 실제 사용자 프롬프트 또는 모델 응답 텍스트는 포함되지 않습니다. 호출자, 메서드, 리소스, 타임스탬프, 상태와 같은 메타데이터가 포함됩니다.	프롬프트 또는 대답 텍스트, 필터 결과, 기타 삭제 세부정보와 같은 전체 페이로드를 포함합니다.
사용 설정 메커니즘	Model Armor API의 표준 Google Cloud IAM 감사 로그 설정입니다. 데이터 액세스 로그는 명시적으로 사용 설정해야 하는 경우가 많습니다. 템플릿 작업의 감사 로그는 자동으로 생성됩니다.	템플릿 메타데이터 또는 최소 기준 설정에서 불리언 플래그 log_sanitize_operations를 설정하여 사용 설정됩니다.
로깅 조건	템플릿 및 바닥 설정에 대한 생성, 읽기, 업데이트, 삭제, 나열 작업을 자동으로 로깅합니다.	Sensitive Data Protection이 사용 설정되어 있는지 또는 필터 설정이 일치하는지 여부와 관계없이 데이터 플레인 요청의 데이터 (사용자 프롬프트 및 모델 응답)를 로깅합니다.
로그 볼륨 및 비용	일반적으로 더 작고 예측 가능하며 표준 Cloud Logging 가격이 적용됩니다.	매우 크고 방대할 수 있으며, 페이로드가 크고 사용 빈도가 높아 Cloud Logging 비용이 크게 발생할 수 있습니다. 페이로드가 큰 경우 여러 로그 항목으로 분할될 수 있습니다.
보안 고려사항	페이로드 데이터가 로깅되지 않으므로 비교적 안전합니다. 액세스하려면 특별한 IAM 권한이 필요합니다 (예: 감사 로그를 볼 수 있는 특정 IAM 역할).	민감한 사용자 데이터 (PII, 기밀 정보)가 포함되어 있습니다. 로그 보기 권한이 있는 사용자 (예: roles/logging.privateLogViewer)가 액세스할 수 있습니다.
권장사항	일반 보안 및 규정 준수 모니터링에 사용 설정합니다.	액세스 제어 싱크 (예: 엄격한 IAM이 적용된 BigQuery)로 안전하게 라우팅되지 않는 한 프로덕션 또는 민감한 정보에는 권장되지 않습니다.

템플릿에서 로깅을 사용 설정하면 원시 프롬프트와 응답이 로깅에 기록됩니다. 이 데이터에는 민감한 사용자 데이터, 개인 식별 정보(PII) 또는 기밀 정보가 포함될 수 있습니다. 트래픽이 많고 페이로드가 크면 로깅 비용이 많이 발생할 수 있으며, 로그 볼륨이 한도를 초과하여 신중한 관리가 필요할 수 있습니다.

감사 로그의 호출자 ID

감사 로그를 보면 Cloud 감사 로그가 protoPayload.authenticationInfo.principalEmail 필드에 호출자의 ID를 캡처합니다. 기록된 ID는 Model Armor API가 호출되는 방식에 따라 달라집니다.

• 직접 API 호출: 사용자 또는 서비스 계정이 Model Armor API를 직접 호출하는 경우 (예: gcloud, 클라이언트 라이브러리 또는 REST API 사용) principalEmail에는 해당 사용자 또는 서비스 계정의 이메일 주소가 포함됩니다.
• 통합된 Google Cloud 서비스를 통한 호출: Model Armor가 Gemini Enterprise Agent Platform과 같은 다른Google Cloud 서비스와 통합되는 경우 principalEmail에는 해당 서비스의 ID가 포함되며, 이는 일반적으로 Google 관리 서비스 계정입니다. 서비스 에이전트의 형식은 service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com입니다. 예를 들어 Gemini Enterprise Agent Platform 기능에서 시작된 호출은 Gemini Enterprise Agent Platform 서비스 에이전트를 사용합니다.

호출자를 구분하려면 감사 로그 항목의 principalEmail 필드를 검사하세요. 최종 사용자 또는 사용자 관리 서비스 계정의 호출에는 이메일 주소가 표시되고, 다른 Google Cloud 서비스를 통한 호출에는 Google 관리 서비스 계정 이메일 주소가 표시됩니다.