Google Cloud는 Google Cloud Monitoring로 프로젝트 안정성을 모니터링하고 Google Cloud Logging 오류 로그로 문제를 디버그하는 도구를 제공합니다. 사용자 인텐트를 처리할 때 오류가 발생할 때마다 Google Home 애널리틱스 파이프라인은 해당 실패를 측정항목에 기록하고 프로젝트 로그에 오류 로그를 게시합니다.
다음 두 단계를 통해 오류를 해결할 수 있습니다.
- 스마트 홈 측정항목으로 프로젝트 상태를 모니터링하세요.
- 오류 로그에서 자세한 오류 설명을 확인하여 문제를 조사합니다.
오류 모니터링
Google Cloud Monitoring dashboard를 사용하여 프로젝트 측정항목에 액세스할 수 있습니다. 다음은 품질 모니터링 및 디버깅에 유용한 주요 차트입니다.
- 성공률 차트는 프로젝트의 신뢰성을 모니터링할 때 시작하는 첫 번째 차트입니다. 이 차트에서 감소는 사용자층의 일부 또는 전체가 중단되었음을 나타낼 수 있습니다. 프로젝트를 변경하거나 업데이트할 때마다 이 차트에 이상이 없는지 자세히 모니터링하는 것이 좋습니다.
- 95번째 백분위수 지연 시간 차트는 사용자를 대상으로 한 스마트 홈 작업의 성능을 나타내는 중요한 지표입니다. 이 차트의 급격한 변동은 시스템이 요청을 따라잡지 못할 수도 있음을 나타낼 수 있습니다. 이 차트를 주기적으로 점검하면 예기치 않은 동작이 있는지 확인하는 것이 좋습니다.
- 오류 분류 차트는 통합의 문제를 해결할 때 가장 유용합니다. 성공률 차트에 강조표시된 모든 오류의 오류 코드가 오류 분석에 표시됩니다. 아래 표에서 Google Home platform에서 표시한 오류와 이를 해결하는 방법을 확인할 수 있습니다.
플랫폼 오류 코드
다음은 Google Home platform에서 포착된 문제를 식별하기 위해 프로젝트 로그에 표시될 수 있는 일반적인 오류 코드입니다. 문제 해결 정보는 다음 표를 참조하세요.
| 오류 코드 | 설명 |
|---|---|
BACKEND_FAILURE_URL_ERROR |
서비스로부터 401이 아닌 HTTP 4xx 오류 코드가 수신되었습니다.
GCP Logging의 requestId를 사용하여 스마트 홈 서비스 로그를 확인합니다.
|
BACKEND_FAILURE_URL_TIMEOUT |
서비스에 연결하는 중에 Google의 요청 시간이 초과되었습니다.
서비스가 온라인 상태이고 연결을 수락하며 용량을 초과하지 않았는지 확인합니다. 또한 대상 기기의 전원이 켜져 있고 온라인 상태이며 동기화되어 있는지도 확인합니다. |
BACKEND_FAILURE_URL_UNREACHABLE |
서비스로부터 HTTP 5xx 오류 코드가 수신되었습니다.
GCP Logging의 requestId를 사용하여 스마트 홈 서비스 로그를 확인합니다.
|
DEVICE_NOT_FOUND |
파트너 서비스 측에 기기가 없습니다.
이는 일반적으로 데이터 동기화 실패 또는 경합 상태를 나타냅니다. |
GAL_BAD_3P_RESPONSE |
페이로드의 형식 또는 값이 잘못되어 Google에서 계정 연결 서비스의 응답을 파싱할 수 없습니다.
GCP Logging의 requestId를 사용하여 계정 연결 서비스의 오류 로그를 확인합니다.
|
GAL_INTERNAL |
Google에서 액세스 토큰을 검색하려고 할 때 Google 내부 오류가 발생했습니다.
GCP Logging에서 이 오류율이 증가하는 경우 Google에 자세한 내용을 문의하세요. |
GAL_INVALID_ARGUMENT |
Google에서 액세스 토큰을 검색하려고 할 때 Google 내부 오류가 발생했습니다.
GCP Logging에서 이 오류율이 증가하는 경우 Google에 자세한 내용을 문의하세요. |
GAL_NOT_FOUND |
Google에 저장된 사용자의 액세스 토큰과 갱신 토큰은 무효화되며 더 이상 갱신할 수 없습니다. 사용자가 서비스를 계속 사용하려면 계정을 다시 연결해야 합니다.
GCP Logging에서 이 오류율이 증가하는 경우 Google에 자세한 내용을 문의하세요. |
GAL_PERMISSION_DENIED |
토큰 공유가 승인되지 않은 상태에서 Google 내부 오류가 발생했습니다.
GCP Logging에서 이 오류율이 증가하는 경우 Google에 자세한 내용을 문의하세요. |
GAL_REFRESH_IN_PROGRESS |
사용자의 액세스 토큰이 만료되었으며 액세스 토큰을 갱신하려는 다른 동시 시도가 이미 진행 중입니다.
이는 문제가 아니며 별도의 조치가 필요하지 않습니다. |
INVALID_AUTH_TOKEN |
서비스로부터 HTTP 401 오류 코드가 수신되었습니다.
액세스 토큰이 만료되지 않았지만 서비스에서 무효화했습니다. GCP Logging의 requestId를 사용하여 스마트 홈 서비스 로그를 확인합니다.
|
INVALID_JSON |
JSON 응답을 파싱하거나 이해할 수 없습니다.
JSON 응답 구조에 대괄호 불일치, 쉼표 누락, 잘못된 문자와 같은 잘못된 구문이 있는지 확인합니다. |
OPEN_AUTH_FAILURE |
사용자의 액세스 토큰이 만료되어 Google에서 갱신할 수 없거나 서비스로부터 HTTP 401 오류 코드가 수신되었습니다.
이 코드의 비율이 증가하면 스마트 홈 인텐트 또는 갱신 토큰 요청과 관련된 오류율이 증가했는지 확인하세요. |
PARTNER_RESPONSE_INVALID_ERROR_CODE |
응답이 인식할 수 없는 오류 코드를 나타냅니다.
요청 응답에 오류가 표시되면 지원되는 오류 코드에서 제공하는 오류를 사용하세요. |
PARTNER_RESPONSE_INVALID_PAYLOAD |
응답 payload 필드는 JSON 객체로 파싱할 수 없습니다.
요청 응답의 페이로드 필드가 대괄호와 일치하고 JSON 필드로 올바르게 구성되었는지 확인합니다. |
PARTNER_RESPONSE_INVALID_STATUS |
응답이 상태를 나타내지 않거나 잘못된 상태를 나타냅니다.
인텐트 처리 요청에 대한 응답은 SUCCESS, OFFLINE, ERROR, EXCEPTIONS 중 하나를 사용하여 상태를 나타내야 합니다. 자세한 내용은
오류 및 예외 처리를 참조하세요.
|
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
요청에 있는 하나 이상의 인텐트가 응답에서 누락되었습니다.
실행 응답이 올바르게 구성되어 있고 요청의 모든 인텐트에 관한 결과가 응답에 있는지 확인합니다. |
PARTNER_RESPONSE_MISSING_DEVICE |
요청에 있는 하나 이상의 기기가 응답에서 누락되었습니다.
실행 응답이 올바르게 구성되었는지, 요청의 모든 기기 ID가 응답에 있는지 확인합니다. |
PARTNER_RESPONSE_MISSING_PAYLOAD |
응답에 payload 필드가 포함되어 있지 않습니다.
요청 응답에 페이로드 필드를 포함해야 합니다. 실행 응답을 올바르게 빌드하는 방법을 자세히 알아볼 수 있습니다. |
PARTNER_RESPONSE_NOT_OBJECT |
응답을 JSON 객체로 파싱할 수 없습니다.
요청 응답의 모든 필드에 의도하지 않은 문자, 대괄호 불일치, 형식 오류가 있는지 확인하세요. 일부 유니코드 문자가 지원되지 않을 수 있습니다. 또한 응답이 JSON 객체로 올바르게 구성되었는지 확인하세요. |
PROTOCOL_ERROR |
요청을 처리하지 못했습니다.
Google Cloud Logging의 requestId를 사용하여 스마트 홈 서비스 로그를 확인합니다.
|
RESPONSE_TIMEOUT |
응답을 기다리는 동안 요청 시간이 초과되었습니다.
응답 전송 제한 시간은 요청 전송 후 9초입니다. 이 시간 내에 응답을 보내야 합니다. |
RESPONSE_UNAVAILABLE |
응답이 수신되지 않거나 응답에 상태가 표시되지 않습니다.
인텐트 처리 요청에 대한 응답은 스마트 홈 문서에 따라 구조화되고 상태를 표시해야 합니다. |
TRANSIENT_ERROR |
일시적인 오류는 저절로 해결되는 오류입니다.
일반적으로 이러한 오류는 기기 또는 서비스와의 연결이 끊어졌을 때 나타납니다. 서버에 대한 새 연결을 열 수 없는 경우에도 마찬가지입니다. |
검색 로그
측정항목을 사용하여 통합을 모니터링하는 데 익숙해졌다면 다음 단계는 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: 스마트 홈 클라우드 통합을 디버그하기 위한 빠른 시작 가이드입니다.
- Local Home 디버깅 Codelab: 스마트 홈 로컬 통합을 디버그하기 위한 빠른 시작 가이드입니다.