소매업의 이름이 소매업용 Vertex AI Search로 변경됩니다. 새로운 브랜딩이 반영되도록 콘텐츠를 업데이트하는 중입니다.

모니터링 및 문제해결

이 페이지에서는 카탈로그 및 사용자 이벤트 가져오기와 소매업용 Vertex AI Search의 기타 API 작업에서 발생한 오류에 대한 정보를 가져오는 방법을 설명합니다.

알림 설정에 대한 도움말은 Cloud Monitoring 알림 설정을 참조하세요.

소개

최고 품질의 결과를 가져오려면 정확한 카탈로그 정보와 사용자 이벤트를 API에 제공하는 것이 중요합니다. 오류 원인을 모니터링하고 이해하면 사이트에서 발생한 오류를 찾아 수정하는 데 도움이 됩니다.

집계된 통합 오류 확인

데이터 업로드 프로세스와 예측 또는 검색 요청으로 생성된 집계 오류를 확인하려면 Monitoring 페이지를 사용합니다.

이 페이지에는 소매용 Vertex AI Search API에 대한 모든 오류가 표시됩니다. 제품 카탈로그, 사용자 이벤트, 추천 예측, 검색 결과, 모델과 관련된 오류가 표시됩니다. 또한 시스템은 Cloud Storage 파일의 잘못된 행과 같은 가져오기 오류도 로깅합니다. 시스템은 가져오기 파일당 최대 100개의 오류를 로깅합니다. 오류가 표시되는 기간을 정의하고 오류 유형을 기준으로 필터링할 수 있습니다.

개별 오류를 클릭하여 Cloud Logging에서 해당 오류의 로그를 볼 수 있습니다.

로그를 확장하여 개별 오류 로그를 열 수 있습니다. 오류 로그는 요청 및 응답 페이로드 및 오류 세부정보를 포함하여 요청에 대한 자세한 내용을 제공합니다. 이 정보를 통해 사이트에서 잘못된 메서드 호출의 위치를 파악할 수 있습니다.

잘못된 JSON 오류의 경우 status 필드를 확장하여 문제에 대한 자세한 정보를 확인할 수 있습니다.

특정 통합 작업의 상태 확인

활동 상태 창에서 특정 통합 작업 상태를 확인할 수 있습니다.

Search for Retail 콘솔에서 데이터> 페이지로 이동합니다.

데이터 페이지로 이동
활동 상태를 클릭합니다.

활동 상태 창에는 제품 카탈로그, 사용자 이벤트, 컨트롤의 장기 실행 작업 상태가 표시됩니다.

이 창에서 특정 통합 작업의 오류를 검사할 수 있습니다.
Cloud Logging에서 로그 파일을 검사하려면 오류가 있는 작업의 세부정보 열에서 로그 보기를 클릭합니다.

Cloud Logging에서 로그 보기

Cloud Logging에서 직접 로그 파일을 열려면 다음 절차를 따르세요. 로그를 보려면 로그 뷰어(roles/logging.viewer) 역할이 있어야 합니다.

Google Cloud 콘솔의 로그 탐색기로 이동합니다. 로그 탐색기로 이동
프로젝트 선택기에서 소매업용 Vertex AI Search 프로젝트를 선택합니다.
리소스 드롭다운 메뉴를 클릭하고 사용된 API > Cloud Retail을 선택합니다.

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

예를 들어 다음 링크는 지난 1시간 동안의 모든 소매업용 Vertex AI Search 오류에 대한 로그를 엽니다.

소매업용 Vertex AI Search 로그 열기

작성할 API 로그를 구성하려면 로깅 구성을 참조하세요.

로깅 구성

Logging에 기록되는 서비스 로그를 구성할 수 있습니다. Logging 구성은 로그를 작성하고, 로깅을 사용 설정 또는 사용 중지하며, 특정 서비스의 기본 로깅 설정을 재정의할 심각도 수준을 설정하는 방법을 제공합니다.

최종 사용자가 수행하는 각 API 요청은 하나의 로깅 항목을 생성할 수 있습니다. 항목에는 API 메서드, 호출된 시점, 응답 코드, 요청 및 응답 본문과 같은 정보가 포함됩니다. 프로젝트의 로깅 구성은 특정 API 서비스의 로깅 구성을 세부적으로 지정하는 옵션과 함께 Logging에 기록되는 API에서 생성된 로그 유형을 지정합니다.

로깅 구성을 업데이트하려면 소매업용 Vertex AI Search 편집자 역할이 필요합니다.

콘솔이나 LoggingConfig API를 사용하여 Logging을 구성할 수 있습니다.

콘솔

콘솔에서 로깅 구성을 업데이트하려면 다음 단계를 수행합니다.

Search for Retail 콘솔에서 Monitoring 페이지로 이동합니다.

Monitoring 페이지로 이동
Logging 구성을 클릭합니다.
전역 로깅 구성을 설정하려면 로깅 수준을 선택합니다. LOG_ALL을 선택하면 성공한 로그의 샘플링 레이트도 입력합니다.
서비스 수준 구성을 설정하려면 업데이트할 서비스를 선택하고 로깅 수준을 선택합니다. 이 설정은 전역 로깅 구성을 재정의합니다.

curl

API를 사용하여 로깅 구성을 업데이트하려면 LoggingConfig 리소스를 사용합니다. LoggingConfig API 참조를 참조하세요.

현재 로깅 구성을 보려면 loggingConfig.Get을 사용합니다.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig"

PROJECT_ID: 프로젝트의 ID입니다.

로깅 구성을 업데이트하려면 loggingConfig.Patch 메서드를 사용합니다. 자세한 내용은 LoggingConfig API 참조를 확인하세요.

이 예시에서는 loggingConfig.Patch를 사용하여 전역 로깅 구성을 LOG_WARNINGS_AND_ABOVE로 설정합니다. 또한 두 가지 서비스 수준 구성을 설정합니다. CatalogService는 LOG_WARNINGS_AND_ABOVE로, ControlService는 LOG_ALL로 설정합니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/loggingConfig" \
  --data '{
    "name": "projects/PROJECT_ID/loggingConfig",
    "default_log_generation_rule": {"logging_level": "LOG_ERRORS_AND_ABOVE"},
    "service_log_generation_rules": [
      {
        "service_name": "CatalogService",
        "log_generation_rule": {
          "logging_level": "LOG_WARNINGS_AND_ABOVE"
          }
      },
      {
        "service_name": "ControlService",
        "log_generation_rule": {
            "logging_level": "LOG_ALL", "info_log_sample_rate": "0.1"
            }
        }
      ]
    }'

Logging 수준

일부 심각도 수준의 로그만 Logging에 기록됩니다. 로깅 수준 설정은 Logging에 기록될 API 메서드로 생성된 로그를 결정합니다.

API 메서드에 서비스 수준 로깅 구성을 설정하지 않으면 전역 로깅 수준 설정이 사용됩니다.

기본 로깅 수준 설정은 LOG_WARNINGS_AND_ABOVE입니다.

logging_level 필드는 다음 값을 허용합니다.

LOGGING_DISABLED: 작성된 로그가 없습니다.
LOG_ERRORS_AND_ABOVE: 오류만 로깅합니다.
LOG_WARNINGS_AND_ABOVE: 오류 및 경고만 로깅합니다.
LOG_ALL: INFO 로그와 같은 성공한 로그를 포함하여 모든 항목을 로깅합니다.

성공한 로그의 샘플링 레이트

로깅 수준 설정을 LOG_ALL로 설정했지만 모든 성공적인 로그를 로깅하지 않으려면 샘플링 레이트를 지정하면 됩니다. 예를 들어 성공적인 상태 확인을 위해 로그를 주기적으로 모니터링하거나 성공한 로그의 비율을 확인해야 할 수 있습니다. 샘플링 레이트를 지정하면 많은 양의 INFO 로그 항목을 Logging에 쓰지 않고도 이를 수행할 수 있으므로 Logging 비용이 증가하는 것을 방지할 수 있습니다.

샘플링 레이트를 지정하려면 info_log_sample_rate를 0보다 크고 1 이하의 유효한 부동 소수점 값으로 설정합니다. 샘플링 레이트는 Logging에 INFO 로그가 기록될 가능성을 결정합니다. 기본값은 1입니다(모든 INFO 로그가 작성됨).

서비스 수준 구성

특정 서비스에 대한 로깅 구성을 설정할 수 있습니다. 그러면 해당 서비스의 전역 로깅 설정을 덮어씁니다. 예를 들어 전역 로깅 수준을 LOG_WARNINGS_AND_ABOVE로 설정했지만 성공적인 사용자 이벤트 통합을 확인할 수 있도록 UserEventService 서비스 로깅 수준을 LOG_ALL로 설정할 수 있습니다.

ServiceLoggingLevel 객체를 사용하여 세분화된 로깅 수준을 설정합니다.

service_name 필드는 다음 값을 허용합니다.

CompletionService
ControlService
MerchantCenterStreaming
ModelService
PredictionService
ProductService
ServingConfigService
UserEventService

오류 유형

이 섹션에서는 로그에 표시될 수 있는 오류 유형에 대한 정의를 제공합니다.

MISSING_FIELD: 필수 필드 값이 설정되지 않았습니다. 예를 들어 카탈로그 항목에 제목이 없습니다.
INVALID_TIMESTAMP: 타임스탬프가 잘못되었습니다. 예를 들어 너무 먼 미래이거나 형식이 잘못되었습니다.
FIELD_VALUE_TOO_SMALL: 필드 값이 필수 최솟값보다 낮습니다. 예를 들어 음수 가격입니다.
INCORRECT_JSON_FORMAT: 요청의 JSON 형식이 잘못되었습니다. 예를 들어 대괄호({)가 누락되었습니다.
INVALID_LANGUAGE_CODE: 언어 코드의 형식이 잘못되었습니다.
FIELD_VALUE_EXCEEDED: 필드 값이 허용되는 최댓값보다 큽니다.
INVALID_RESOURCE_ID: 리소스 ID가 잘못되었습니다. 예를 들어 리소스 이름에 존재하지 않는 catalog_id가 있습니다.
FIELD_SIZE_EXCEEDED: 필드의 항목 수가 최대 한도를 초과합니다.
UNEXPECTED_FIELD: 비어 있어야 하는 필드에 값이 있습니다. 예를 들어 세부정보 페이지 조회 이벤트에 대한 트랜잭션이 있습니다.
INVALID_FORMAT: 필드 형식이 잘못되었습니다. 예를 들어 잘못된 형식의 문자열이 있습니다.
RESOURCE_ALREADY_EXISTS: 이전에 만든 카탈로그 항목과 같이 이미 존재하는 리소스를 만들려고 했습니다.
INVALID_API_KEY: API 키가 요청의 프로젝트와 일치하지 않습니다.
INSUFFICIENT_PERMISSIONS: 요청을 실행할 권한이 없습니다. 이 오류는 일반적으로 필요한 IAM 권한 누락과 관련이 있습니다.
UNJOINED_WITH_CATALOG: 카탈로그에 없는 카탈로그 항목 ID가 요청에 포함되어 있습니다. 카탈로그가 최신 상태인지 확인하세요.
BATCH_ERROR: 요청에 여러 오류가 있습니다. 예를 들어 여러 가지 이유로 검증에 실패한 10개의 항목이 포함된 인라인을 가져오는 경우입니다.
INACTIVE_RECOMMENDATION_MODEL: 제공할 수 없는 모델을 쿼리했습니다.
ABUSIVE_ENTITY: 요청과 연결된 방문자 ID 또는 사용자 ID가 짧은 기간 동안 비정상적인 이벤트 수를 보냈습니다.
FILTER_TOO_STRICT: 예측 요청 필터가 모든 예측 결과를 차단했습니다. 호출에서 strictFiltering을 false로 지정하지 않는 한(항목이 반환되지 않음) 맞춤설정되지 않은 일반 인기 항목이 반환됩니다. 이 문제가 발생하는 일반적인 이유는 다음과 같습니다.
- 카탈로그에 없는 필터 태그를 지정하고 있습니다. 필터 태그 업데이트가 적용되는 데 최대 하루가 걸릴 수 있습니다.
- 필터 범위가 너무 좁습니다.

데이터 로드 측정항목 보기

Google Cloud 콘솔에서 카탈로그 및 사용자 이벤트 데이터 수집을 모니터링하려면 다음 단계를 수행합니다.

모니터링 페이지에서 카탈로그와 사용자 이벤트 데이터 수집에 대한 오류 측정항목을 봅니다.

Monitoring 페이지로 이동
데이터 업로드 시스템이 성공적으로 실행되면 데이터 페이지의 카탈로그 및 이벤트 탭을 사용하여 카탈로그에 대한 합산 데이터를 확인하고 업로드된 제품을 미리 보고 사용자 이벤트 통합 측정항목의 시각화를 봅니다.

데이터 페이지로 이동
데이터 업로드에 문제가 있는지 알려주는 알림을 만들려면 Cloud Monitoring 알림 설정 절차를 따르세요.

카탈로그 데이터 요약

데이터 페이지의 카탈로그 탭을 사용하여 각 카탈로그 분기에 대한 대략적인 데이터 통계를 확인하세요. 이 페이지에는 가져온 제품 수, 재고 수량, 각 제품 카탈로그 분기에서 마지막으로 제품을 가져온 시간이 표시됩니다.

또한 업로드한 카탈로그 항목의 미리보기를 보고 제품 필드를 기준으로 필터링할 수도 있습니다.

추천 또는 검색 결과를 스테이징하고 미리 볼 수 있도록 데이터를 여러 브랜치로 가져올 수 있습니다. 예를 들어 연말연시를 준비하기 위해 기본이 아닌 브랜치에 새 카탈로그 데이터를 업로드하고 웹사이트에 게시하기 전에 소매업용 Vertex AI Search 결과가 올바르게 생성되었는지 확인할 수 있습니다.

사용자 이벤트 기록 통계

각 사용자 이벤트 유형에 대해 이벤트 탭에서 기록된 이벤트 수, 제품과 연결되지 않은 이벤트 수(조인되지 않은 이벤트), 이전 기간과의 숫자 차이를 확인할 수 있습니다. 미리 설정된 기간을 선택하거나 커스텀 기간을 입력할 수 있습니다.

측정항목 그래프에는 시간 경과에 따라 수집된 사용자 이벤트가 표시되며 해당 이벤트는 사용자 이벤트 유형별로 필터링할 수 있습니다.

데이터 품질 측정항목

데이터 품질 페이지에서 검색의 권장 데이터 품질 기준을 충족하는 제품과 사용자 이벤트의 비율을 보여주는 측정항목을 확인할 수 있습니다. 이 페이지를 사용하여 검색 결과 품질을 개선하고 검색 성능 등급을 잠금 해제하기 위해 가져오거나 업데이트해야 하는 데이터를 평가합니다.

검색 성능 등급과 데이터 품질 확인에 대한 자세한 내용은 검색 성능 등급 잠금 해제를 참조하세요.

모든 카탈로그 데이터 품질 측정항목 목록은 카탈로그 데이터 품질 측정항목을 참조하세요.

추천 및 검색의 모든 사용자 이벤트 요구사항과 추천은 사용자 이벤트 요구사항 및 권장사항을 참조하세요.

조인되지 않은 이벤트

사용자 이벤트 또는 API 요청에서 소매업용 Vertex AI Search에 업로드되지 않은 제품을 참조하는 경우 이를 조인되지 않은 이벤트라고 합니다. 조인되지 않은 사용자 이벤트는 계속 로깅되고 조인되지 않은 요청은 처리되지만 향후 예측을 위해 모델을 향상시킬 목적으로 사용될 수 없습니다. 따라서 사용자 이벤트와 예측 요청 모두에 로깅되지 않은 이벤트 비율이 매우 낮도록 해야 합니다.

조인되지 않은 사용자 이벤트 비율은 데이터 페이지의 이벤트 탭에서 확인할 수 있습니다.

API 오류

Monitoring 페이지의 버튼 모음에서 API 측정항목 보기를 클릭하면 시간 경과에 따라 메서드 이름별로 표시된 API 오류 그래프를 볼 수 있습니다.

API 메서드 활동 모니터링

API 메서드로 트래픽, 오류, 지연 시간을 시각화하려면 Monitoring 페이지로 이동합니다. 미리 설정된 기간을 선택하거나 커스텀 기간을 입력할 수 있습니다.

각 그래프에 대한 세부정보를 보려면 다음 안내를 따르세요.

그래프 아래에 있는 메서드 이름을 클릭하여 그래프에서 격리합니다.
그래프 위로 마우스 커서를 가져가면 해당 시점의 각 메서드와 값이 포함된 콜아웃이 표시됩니다.
그래프의 한 섹션을 클릭하고 드래그하여 해당 기간을 확대합니다.

다음 단계

데이터 피드에 오류 알림을 설정하는 방법 알아보기
Error Reporting에 대해 자세히 알아보기
Logging에서 로그 보기에 대해 자세히 알아보기