Google Cloud은 Google Cloud Monitoring로 프로젝트의 안정성을 모니터링하고 Google Cloud Logging 오류 로그로 문제를 디버그하는 도구를 제공합니다. 사용자 의도를 충족할 때 실패가 발생하면 Google Home 분석 파이프라인이 측정항목에 실패를 기록하고 프로젝트 로그에 오류 로그를 게시합니다.
오류를 해결하는 방법은 두 가지입니다.
- 스마트 홈 측정항목으로 프로젝트 상태를 모니터링하세요.
- 오류 로그에서 자세한 오류 설명을 확인하여 문제를 조사합니다.
원하는 경우 다른 사용자와 공유하여 작업을 테스트할 수 있습니다. 오류와 예외를 적절하게 처리해야 합니다.
오류 모니터링
Google Cloud Monitoring dashboards를 사용하여 프로젝트 측정항목에 액세스할 수 있습니다. 특히 품질을 모니터링하고 디버깅하는 데 유용한 주요 차트가 있습니다.
- 성공률 차트는 프로젝트의 안정성을 모니터링할 때 가장 먼저 시작하는 차트입니다. 이 차트의 감소는 사용자층의 일부 또는 전체에 대한 서비스 중단을 나타낼 수 있습니다. 프로젝트를 변경하거나 업데이트한 후 이 차트에서 비정상적인 부분이 있는지 면밀히 모니터링하는 것이 좋습니다.
- 95번째 백분위수 지연 시간 차트는 사용자에게 Cloud-to-cloud 통합이 어떻게 작동하는지 보여주는 중요한 지표입니다. 이 차트의 갑작스러운 변동은 시스템이 요청을 따라가지 못할 수 있음을 나타냅니다. 예상치 못한 동작이 있는지 확인하려면 이 차트를 주기적으로 확인하는 것이 좋습니다.
- 오류 분류 차트는 통합 문제를 해결할 때 가장 유용합니다. 성공률 차트에 강조 표시된 모든 오류에 대해 오류 코드가 오류 분류에 표시됩니다. 아래 표에서 Google Home platform가 표시한 오류와 문제 해결 방법을 확인할 수 있습니다.
일반적인 플랫폼 오류 코드
다음은 프로젝트 로그에서 Google Home platform에 의해 포착된 문제를 식별하기 위해 표시될 수 있는 일반적인 오류 코드입니다. 문제 해결 정보는 다음 표를 참고하세요. 전체 오류 코드 목록은 오류 및 예외를 참고하세요.
| 오류 코드 | 설명 | 파트너 조치 가능 |
|---|---|---|
ACTION_NOT_AVAILABLE |
이 명령어는 기기의 현재 상태에 유효하지 않습니다 (예: 기기가 꺼져 있는 동안 '온도 설정').
주문 처리에서 기기 특성 및 현재 상태 로직을 확인합니다. |
예 |
AGENT_ISSUE |
파트너의 클라우드 에이전트에서 일반적인 문제가 발생했습니다.
이행 로그에서 처리되지 않은 예외 또는 비정상 종료가 있는지 확인합니다. |
예 |
AGENT_UNAVAILABLE_ERROR |
Google에서 파트너의 주문 처리 URL에 연결할 수 없습니다.
서버가 온라인 상태이고 방화벽이 Google을 차단하지 않으며 URL이 올바른지 확인합니다. |
예 |
APP_LAUNCH_FAILED |
타겟 기기에서 서드 파티 앱을 실행하지 못했습니다.
appId를 확인하고 앱이 타겟 하드웨어에서 지원되는지 확인합니다. |
예 |
AUTH_EXPIRED |
OAuth 액세스 토큰이 만료되어 갱신할 수 없습니다.
갱신 토큰 순환을 확인하고 사용자가 액세스 권한을 취소하지 않았는지 확인합니다. |
예 |
BACKEND_FAILURE_URL_TIMEOUT |
Google이 서비스에 연결하려고 할 때 요청 시간이 초과되었습니다.
서비스가 온라인 상태이고 연결을 수락하며 용량을 초과하지 않는지 확인합니다. 또한 타겟 기기의 전원이 켜져 있고, 온라인 상태이며, 동기화되어 있는지 확인합니다. |
|
BACKEND_FAILURE_URL_UNREACHABLE |
Google에서 서비스로부터 HTTP 5xx 오류 코드를 수신했습니다.
Google Cloud Logging의 requestId을 사용하여 스마트 홈 서비스 로그를 확인합니다.
|
|
CHANNEL_SWITCH_FAILED |
기기에서 요청된 미디어 채널로 전환할 수 없습니다.
사용자의 채널 이름/번호와 구독 상태를 확인합니다. |
예 |
CHARGER_ISSUE |
기기에서 충전 시스템에 하드웨어 문제가 있다고 보고합니다.
파트너는 하드웨어 수준 원격 분석 및 배터리 상태를 조사해야 합니다. |
예 |
CHECK_PARTNER_APP |
이 오류를 해결하려면 사용자가 파트너의 앱을 열어야 합니다.
복잡한 UI 상호작용 (예: 펌웨어 업데이트)이 필요한 오류에 이 코드를 사용합니다. |
예 |
COMMAND_FAILED |
명령어 실행 중에 일반적인 오류가 발생했습니다.
이행 로그에서 특정 requestId를 확인하여 근본 원인을 찾으세요.
|
예 |
COMMAND_INSERT_FAILED |
Google에서 기기의 명령어를 대기열에 추가하거나 처리할 수 없습니다.
데이터베이스 쓰기 성능 또는 내부 명령 대기열 로직을 조사합니다. |
예 |
DEVICE_NOT_FOUND |
요청의 기기 ID가 파트너 측에 없습니다.
사용자가 기기를 추가하거나 삭제할 때 클라우드에서 requestSync이 트리거되는지 확인합니다.
|
예 |
ERROR_STATUS |
대답에 코드가 없는 비특정 'ERROR' 상태가 표시되었습니다.
사용자 TTS 및 대시보드 데이터를 개선하려면 항상 특정 errorCode 문자열을 포함하세요.
|
예 |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
Google이 이행에서 HTTP 4xx 오류 (401 제외)를 수신했습니다.
웹 서버 로그에서 403, 404 또는 400 응답을 확인합니다. |
예 |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
주문 처리 URL이 robots.txt 또는 보안 필터에 의해 차단되었습니다.
Google 크롤러/서비스가 이행 엔드포인트에 액세스할 수 있는지 확인합니다. |
예 |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
Google이 주문 처리 서비스로부터 HTTP 5xx 오류를 수신했습니다.
서버 다운, 타임아웃 또는 502/503 게이트웨이 오류를 조사합니다. |
예 |
EXECUTION_BAILOUT_INVALID_RESPONSE |
JSON 응답의 형식이 잘못되어 처리가 중단되었습니다.
JSON 유효성 검사기를 사용하여 대답이 의도 스키마를 엄격하게 따르는지 확인하세요. |
예 |
EXECUTION_GAL_BAD_3P_RESPONSE |
토큰 응답의 형식이 잘못되어 계정 연결에 실패했습니다.
OAuth 서버의 응답 형식이 Google의 요구사항과 일치하는지 확인합니다. |
예 |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
사용자 계정에 이 작업을 수행하는 데 필요한 권한이 없습니다.
OAuth 중에 요청된 범위를 확인하고 필수 특성과 일치하는지 확인합니다. |
예 |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
파트너 클라우드는 사용자가 계정을 연결 해제했음을 나타냅니다.
agentUserId 매핑이 안정적이고 삭제되지 않았는지 확인합니다.
|
예 |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
통합이 파트너 측에서 읽기 전용 상태입니다.
사용자의 계정이 정지되었는지 또는 '보기 전용' 유지관리 모드인지 확인합니다. |
예 |
EXECUTION_GAL_UNLINKED_BY_3P |
서드 파티 서비스에서 계정을 선제적으로 연결 해제했습니다.
사용자의 연결이 끊긴 이유를 조사합니다 (예: 보안 재설정). |
예 |
EXECUTION_INVALID_JSON |
Google에서 JSON 응답 페이로드를 파싱할 수 없습니다.
대답에 문법 오류, 누락된 괄호 또는 잘못된 문자가 있는지 확인합니다. |
예 |
FAULTY_BATTERY |
기기 하드웨어에서 배터리가 고장났거나 방전되었다고 보고합니다.
TTS 또는 앱을 사용하여 사용자에게 실제 배터리를 교체하도록 안내합니다. |
예 |
FUNCTION_NOT_SUPPORTED |
요청한 모드 또는 기능이 기기에서 지원되지 않습니다.
SYNC 응답이 기기의 기능을 정확하게 반영하는지 확인합니다.
|
예 |
HARD_ERROR |
수동 개입 없이는 해결되지 않는 일시적이지 않은 오류입니다.
영구적인 하드웨어 오류 또는 복구할 수 없는 계정 상태에 사용합니다. |
예 |
INVALID_AUTH_TOKEN |
Google에서 서비스로부터 HTTP 401 오류 코드를 수신했습니다.
액세스 토큰이 만료되지 않았지만 서비스에서 무효화했습니다. Google Cloud Logging의 requestId을 사용하여 스마트 홈 서비스 로그를 확인합니다.
|
|
INVALID_JSON |
응답 구조가 잘못되었습니다 (예: 필수 필드가 누락됨).
인텐트 JSON 스키마에 대해 대답을 검증합니다. |
예 |
LOCK_FAILURE |
스마트 도어락이 요청된 상태로 이동할 수 없습니다.
도어락 하드웨어의 물리적 걸림, 전원 부족 또는 모터 고장을 조사합니다. |
예 |
MALFORMED_JSON |
JSON 구조가 깨졌습니다 (예: 닫히지 않은 문자열 또는 객체).
처리가 표준 JSON 라이브러리를 사용하여 응답을 직렬화하는지 확인합니다. |
예 |
MISSING_STATE |
QUERY 응답에 요청된 기기 상태가 포함되지 않았습니다.
SYNC에 정의된 모든 특성이 모든 QUERY 응답에 반영되는지 확인합니다.
|
예 |
NETWORK_PROFILE_NOT_RECOGNIZED |
요청된 네트워크 프로필을 기기에서 알 수 없습니다.
프로필 이름 문자열이 SYNC 응답에서 지원되는 프로필과 일치하는지 확인합니다.
|
예 |
NOT_IMPLEMENTED |
요청된 인텐트 또는 특성이 파트너에 의해 구현되지 않았습니다.
SYNC 응답에는 완전히 구현한 특성만 포함하세요.
|
예 |
OAUTH_RECONNECT_CALL_TO_ACTION |
사용자에게 계정을 다시 연결하라는 알림을 트리거합니다.
사용자의 세션이 무효화되어 수동 OAuth 재인증이 필요한 경우에 사용합니다. |
예 |
OPEN_AUTH_FAILURE |
사용자의 액세스 토큰이 만료되어 Google에서 갱신할 수 없거나 Google에서 서비스로부터 HTTP 401 오류 코드를 수신했습니다.
이 코드의 비율이 증가하는 경우 스마트 홈 인텐트 또는 새로고침 토큰 요청과 관련된 오류 비율도 증가하는지 확인하세요. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
반환된 errorCode 문자열이 Google에서 지원하는 목록에 없습니다.
내부 오류를 공식 오류 목록에 매핑합니다. |
예 |
PARTNER_RESPONSE_INVALID_PAYLOAD |
대답의 payload 필드가 유효한 JSON 객체가 아닙니다.
이행 응답의 루트 구조를 확인합니다. |
예 |
PARTNER_RESPONSE_INVALID_STATUS |
status 응답이 SUCCESS, ERROR 또는 OFFLINE이 아닙니다.
대답의 모든 기기 결과에 유효한 상태 문자열이 포함되어 있는지 확인합니다. |
예 |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
응답에 요청된 모든 명령어/기기의 결과가 포함되지 않았습니다.
요청의 commands 배열에 있는 모든 항목에는 해당하는 응답 항목이 있어야 합니다.
|
예 |
PARTNER_RESPONSE_MISSING_DEVICE |
Google에서 요청한 특정 기기가 응답에서 생략되었습니다.
요청 페이로드에 제공된 모든 ID이(가) 대답에 포함되어 있는지 확인합니다.
|
예 |
PARTNER_RESPONSE_MISSING_PAYLOAD |
대답에 필수 payload 필드가 누락되었습니다.
최상위 JSON 객체에 payload 키가 포함되어 있는지 확인합니다.
|
예 |
PARTNER_RESPONSE_NOT_OBJECT |
전체 응답을 JSON 객체로 파싱할 수 없습니다.
HTTP 응답 본문에 후행 문자 또는 JSON이 아닌 콘텐츠가 있는지 확인합니다. |
예 |
PROTOCOL_ERROR |
기본 통신 프로토콜에서 오류가 발생했습니다.
HTTP 헤더 문제 또는 SSL/TLS 핸드셰이크 실패를 조사합니다. |
예 |
RELINK_REQUIRED |
통합을 계속 사용하려면 사용자가 계정을 다시 연결해야 합니다.
갱신 토큰이 영구적으로 유효하지 않은 경우 서버가 이 코드를 반환하는지 확인합니다. |
예 |
REQUEST_ID_NOT_FOUND |
Google에서 요청의 내부 추적 ID를 찾을 수 없습니다.
일반적으로 내부 플랫폼 오류입니다. 급증을 모니터링하고 지원팀에 문의하세요. |
예 |
RESOURCE_UNAVAILABLE |
요청된 리소스 (기기 또는 특성)를 사용할 수 없습니다.
기기가 'Busy'인지 또는 일시적으로 사용 중지되었는지 확인합니다. |
예 |
RESPONSE_TIMEOUT |
이행 서비스가 9초 이내에 응답하지 못했습니다.
백엔드 지연 시간 최적화: 느린 DB 쿼리 또는 리전 네트워크 지연 시간 확인 |
예 |
RESPONSE_UNAVAILABLE |
파트너 주문 처리 URL에서 응답을 받지 못했습니다.
서비스가 실행 중이고 엔드포인트가 비정상 종료되지 않는지 확인합니다. |
예 |
SCENE_CANNOT_BE_APPLIED |
요청된 장면을 활성화할 수 없습니다 (예: 기기가 누락됨).
파트너 클라우드에서 사용자 장면의 내부 상태를 확인합니다. |
예 |
STREAM_UNPLAYABLE |
카메라 스트림을 시작할 수 없거나 실패했습니다.
WebRTC/HLS 신호를 확인하고 스트림 URL이 유효한지 확인합니다. |
예 |
TIMEOUT |
인텐트를 처리하는 중에 일반적인 시간 초과가 발생했습니다.
클라우드와 기기 허브 간 내부 서비스 시간 초과에 관한 로그를 확인합니다. |
예 |
TRANSIENT_ERROR |
일시적인 오류는 자동으로 해결되는 오류입니다.
이러한 오류는 일반적으로 기기 또는 서비스와의 연결이 끊어지는 것으로 나타납니다. 서버에 대한 새 연결을 열 수 없는 경우에도 마찬가지입니다. |
|
UNABLE_TO_LOCATE_DEVICE |
위치 추적기 특성을 사용하여 기기를 찾을 수 없습니다 (예: 핑 실패).
기기의 로컬 연결 (Wi-Fi/블루투스)을 확인합니다. |
예 |
UNABLE_TO_RING_DEVICE |
기기에 연결되었지만 벨소리/알림 기능을 트리거할 수 없습니다.
하드웨어의 알림/스피커 상태와 볼륨 수준을 확인합니다. |
예 |
UNABLE_TO_SILENCE_DEVICE |
기기에서 활성 알림/벨소리를 중지할 수 없습니다.
클라우드와 실제 기기 간의 통신 실패를 조사합니다. |
예 |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
예기치 않은 오류가 발생했습니다. 사용자가 파트너 앱을 확인해야 합니다.
Google에서 지원하는 특정 상응 항목이 없는 오류의 포괄적인 용도로 사용합니다. |
예 |
UNKNOWN_ERROR |
추가 세부정보가 제공되지 않은 일반적인 실패입니다.
문제 해결을 개선하기 위해 더 구체적인 오류 코드로 대체하는 것이 좋습니다. |
예 |
UNLOCK_FAILURE |
스마트 도어락이 '잠금 해제됨' 상태에 도달할 수 없습니다.
하드웨어 걸림, 배터리 부족 또는 잘못된 PIN 입력에 대해 조사합니다. |
예 |
검색 로그
측정항목을 사용하여 통합을 모니터링하는 데 익숙해지면 다음 단계는 Cloud Logging를 사용하여 특정 오류를 해결하는 것입니다. 오류 로그는 시간, 오류 코드, 시작 스마트 홈 인텐트에 관한 세부정보와 같은 유용한 정보가 포함된 필드가 있는 JSON과 유사한 항목입니다.
Google Cloud에는 항상 프로젝트에 로그를 전송하는 시스템이 여러 개 있습니다. 로그를 필터링하는 쿼리를 작성하여 필요한 로그를 찾아야 합니다. 쿼리는 기간, 리소스, 로그 심각도 또는 맞춤 항목을 기반으로 할 수 있습니다.
쿼리 버튼을 사용하여 맞춤 필터를 빌드할 수 있습니다.
기간을 지정하려면 기간 선택 버튼 을 클릭하고 제공된 옵션 중 하나를 선택합니다. 이렇게 하면 로그가 필터링되어 선택한 기간에 발생한 로그가 표시됩니다.
리소스를 지정하려면 리소스 드롭다운을 클릭한 다음 Google 어시스턴트 작업 프로젝트를 선택합니다. 이렇게 하면 프로젝트에서 시작된 로그를 표시하는 필터가 쿼리에 추가됩니다.
심각도 버튼을 사용하여 긴급, 정보, 디버그 및 기타 심각도 로그 수준별로 필터링합니다.
Logs Explorer의 쿼리 필드를 사용하여 맞춤 항목을 입력할 수도 있습니다. 이 필드에서 사용하는 쿼리 엔진은 문자열 일치와 같은 기본 쿼리와 비교 연산자 (<, >=, !=) 및 불리언 연산자 (AND, OR, NOT)를 포함한 고급 유형의 쿼리를 모두 지원합니다.
예를 들어 아래의 맞춤 항목은 LIGHT 기기 유형에서 발생하는 오류를 반환합니다.
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
쿼리 라이브러리를 방문하여 로그를 효과적으로 쿼리하는 방법을 자세히 알아보세요.
수정사항 테스트
오류를 식별하고 업데이트를 적용하여 오류를 수정했다면 Google Home Test Suite를 사용하여 수정사항을 철저히 테스트하는 것이 좋습니다. 변경사항을 효과적으로 테스트하는 방법을 안내하는 Test Suite 사용법에 관한 사용자 가이드가 제공됩니다.
학습 리소스
이 문서에서는 스마트 홈 작업의 오류를 해결하는 단계를 설명합니다. Codelab에서 디버깅에 대해 자세히 알아볼 수도 있습니다.
- 스마트 홈 디버깅 Codelab: 스마트 홈 클라우드 통합을 디버깅하기 위한 빠른 시작 가이드입니다.
- 로컬 홈 디버깅 Codelab: 스마트 홈 로컬 통합을 디버깅하기 위한 빠른 시작 가이드입니다.