1. 시작하기 전에
이 Codelab은 생태계 품질과 사용자 환경을 개선하기 위해 클라우드 통합을 사용하는 Google Home 파트너와 개발자를 위해 설계되었습니다.
학습할 내용
Google Home vitals 대시보드는 개발자와 파트너가 Google Home 통합의 운영 상태를 모니터링할 수 있는 중앙 정보 소스 역할을 합니다. 지연 시간과 안정성이 사용자 환경을 정의하는 생태계에서 Google Home Vitals는 사후 대응 문제 해결에서 사전 대응 품질 관리로 전환하는 데 필요한 모든 심층 분석이 포함된 셀프 서비스 포털입니다.
- 품질 통합 점수 계산 방법
- 대시보드를 읽고 사용하는 방법
- 품질이 낮은 측정항목을 디버깅하는 방법
필요한 항목
- Google Home 클라우드 통합이 있어야 합니다.
설정
Google Home 활력 징후 대시보드로 이동하는 방법:
- Google Cloud Platform 열기
- Monitoring > 대시보드
- 'Google Home Vitals (클라우드)' 대시보드를 클릭합니다.
2. 대시보드 읽는 방법
품질평가점수 계산 - '양호' 표준과 '불량' 표준
대시보드에는 품질 평가 점수의 세부사항이 설명되어 있습니다. 품질 점수는 기기 유형 세부사항에 따라 할당됩니다. 기기 유형 통합이 양호한 것으로 간주되려면 다음 네 가지 기준을 동시에 충족해야 합니다.
- 전체 성공률: 전체 파트너-Google 통화 성공률이 99.5% 이상이어야 합니다.
참고: 전체 성공률(99.5% 이상)을 충족하지 않으면 개별 기기 성능과 관계없이 전체 프로젝트에 나쁨 등급이 자동으로 부여됩니다. - 명령어 안정성: 모든 기기 유형에서 QUERY 및 EXECUTE 성공률이 99.5% 이상이어야 합니다.
- 응답성 지연 시간: 모든 기기 유형에서 QUERY 및 EXECUTE의 90번째 백분위수 지연 시간이 1,000ms 이하여야 합니다.
- 상태 무결성: 상태 정확도가 99.5% 이상이어야 합니다.
이러한 측정항목이 중요한 이유
- 전체 성공률: 통합 수준의 파트너-Google 호출은 클라우드에서 Google로의 호출 상태를 측정합니다. 성공률이 99.5% 이상이면 Google Home에서 올바른 기기 상태를 사용합니다. 기기가 추가 및 삭제되고, 자동화가 트리거되고, 기록 이벤트가 Google Home 앱의 활동 탭에 표시되는지 확인하는 것이 그 예입니다.
- 명령 안정성: QUERY 및 EXECUTE 성공률은 기기 유형 수준에서 측정되며, 성공률이 99.5% 이상이면 사용자의 명령이 올바르게 실행됩니다 (예: '기기에 연결할 수 없습니다'와 같은 어시스턴트 응답을 피하거나 실행되지 않은 명령을 잘못 확인하지 않음).
- 응답성 지연 시간: QUERY 및 EXECUTE 지연 시간도 기기 유형 수준에서 측정됩니다. 기기 유형당 지연 시간이 1, 000ms 이하이면 사용자가 원하는 작업을 수행하기 위해 너무 오래 기다리지 않아도 됩니다 (예: 조명이 꺼질 때까지 몇 초 동안 기다림).
- 상태 무결성: 상태 정확도 Google 시스템에 저장되고 사용자 쿼리를 제공하는 데 사용되는 상태의 정확도를 측정합니다. 이러한 수치가 낮으면 사용자가 기기 상태를 보거나 'Home에게 물어보기'와 같은 AI 기능을 사용할 때 기기에 대한 잘못된 결과가 표시될 수 있습니다. 자동화가 실행되지 않고 기록 항목이 활동에 올바른 시간에 표시되지 않을 수 있습니다.
대시보드 읽는 방법
통합의 기본 상태 지표 역할을 하는 품질평가점수 측정항목 섹션에서 시작하세요. 우수한 기기 수준 등급은 이 섹션의 모든 측정항목이 녹색 성공 기준을 충족하는지에 따라 결정됩니다. 자세한 기술 요구사항 및 측정항목 정의는 Developer Center 문서에서 확인할 수 있습니다.
Google Home Vitals 대시보드 상단의 '품질 측정항목 점수' 섹션에는 통합 품질평가점수를 계산하는 데 사용되는 측정항목이 반영됩니다.
범례
- 녹색 (양호): 측정항목이 품질 기준을 충족합니다.
- 빨간색 (나쁨): 측정항목이 품질 기준점을 충족하지 않습니다.
예:
아래 예에서 AC_UNIT 기기 유형은 QUERY 및 EXECUTE 성공률과 QUERY 지연 시간 섹션의 품질 기준을 충족하지만 EXECUTE 지연 시간 막대 (빨간색)는 충족하지 않습니다. 즉, 명령어가 통과 비율로 성공하고 있지만 실행 지연 시간이 36ms 너무 느립니다. 시스템 상태 섹션에는 통합 전반의 집계된 메서드에 대해 98.92% 의 실패율이 표시됩니다. 이는 Google Home에 대한 사용자 기기 상태의 정확성을 보장하기 위해 개선의 여지가 있음을 의미합니다. 이는 호출 (DeleteAgentUser, Query, ReportStateAndNotification, RequestSyncDevices 또는 Sync)의 1.08% 가 2xx 또는 5xx와 같지 않은 응답 코드를 반환한다는 의미입니다 (예: 404 오류). AC_UNIT 기기 유형의 통과/실패 품질을 측정하는 데 사용되는 마지막 측정항목은 상태 정확도입니다. 이 예에서는 성공률이 77.43% 이므로 사용자에게 기기에 대한 부정확한 결과가 표시될 수 있습니다. 이 세 가지 측정항목을 기준으로 AC_UNIT의 전체 점수는 '나쁨'이며 품질 기준 미만입니다.
이러한 각 품질 계산은 아래의 디버깅 섹션에 해당합니다. 접힌 단계를 열어 추가 디버깅을 진행합니다.
QUERY/EXECUTE 성공률 및 지연 시간을 디버그하려면 '1단계: 클라우드 호출 검증'으로 이동하세요.
파트너에서 Google로의 성공률을 디버그하려면 '2단계: Google 호출 유효성 검사'로 이동하세요.
각 기기 유형의 상태 정확도를 디버그하려면 '3단계: 상태 정확도 개선'으로 이동하세요.
3. 디버깅 1단계: 클라우드 호출 검증
1단계: 개요
이 섹션에서는 Google에서 클라우드 백엔드로의 통신 상태를 측정하는 측정항목인 클라우드 호출 (Google-파트너 측정항목이라고도 함)에 중점을 둡니다. 여기에는 Query, Execute와 같은 명령어가 포함됩니다.
Google에서는 쿼리 및 실행의 성공률과 지연 시간을 추적합니다. 이는 기기 유형 품질 점수에 반영됩니다.
아래 개요에는 통합 수준의 집계된 QUERY, EXECUTE 성공률과 오류가 표시됩니다. 1a~1d단계에서는 기기 유형/특성 수준에서 이러한 측정항목의 분류를 보여줍니다. 
1a단계와 1b단계에서는 시간 경과에 따른 처리 요청 수, 오류 수, 특정 오류 상태의 추세를 보여줍니다.
1a단계: 쿼리 오류 검토
1b단계: 실행 오류 검토
1c단계와 1d단계에서는 통합 수준과 기기 유형 수준 모두에서 이러한 측정항목의 90번째 백분위수와 50번째 백분위수의 세부사항을 보여줍니다.
1c단계: 쿼리 지연 시간 검토
1d단계: 실행 지연 시간 검토
4. 디버깅 2단계: Google 호출 유효성 검사
2단계: 개요
Google에서 파트너로의 호출을 디버깅한 후 이 두 번째 단계에서는 파트너 클라우드에서 Google로의 호출을 디버깅합니다. 이 섹션에서는 기기 유형 수준이 아닌 파트너 통합 수준의 측정항목을 다룹니다. 여기에는 400 잘못된 요청, 404 찾을 수 없음, 429 리소스 소진과 같은 응답 코드가 포함됩니다.
2a단계: 할당량 문제 디버그
Google Home에는 리소스 할당 및 사용에 대한 제한이 있으며 프로젝트 단위로 적절한 할당량을 적용합니다. Google은 클라우드 간 통합별로 쿼리, 삭제, 보고 상태, 비동기 요청 동기화 API 호출의 집계에 60초당 6,000개의 기본 한도를 적용합니다.
할당량 문제가 발생하면 상태 업데이트를 완료하지 못해 불일치가 발생할 수 있으므로 보고서 상태 정확도에 부정적인 영향을 미칠 수 있습니다. 아래에는 보고서 상태 및 요청 동기화 오류, API 메서드별 개수 및 오류, 할당량 사용량 비율을 구체적으로 보여주는 차트가 있습니다. 이러한 차트에 예상치 못한 트래픽 증가가 표시되면 통합을 검토하여 변경사항으로 인해 Home Graph API로 전송되는 트래픽이 증가하는지 확인하세요.
시간이 지남에 따라 트래픽이 자연스럽게 증가하는 경우 (예: 기기 수 증가, 새로운 기기 유형 출시 또는 기타 예상되는 출시와 일관된 증가) 통합의 할당량을 늘리는 것이 적절할 수 있습니다. 할당량 상향을 요청하려면 개발자 문서에 나와 있는 단계를 따르세요.
5. 디버깅 3단계: 상태 정확도 개선
3단계: 개요
1단계와 2단계의 디버깅이 완료되면 3단계에서는 사용자 쿼리를 처리하는 데 사용되는 Google 시스템에 저장된 기기 상태인 상태 보고의 정확성을 다룹니다. 특성 및 기기 유형별 분류는 아래에 표시됩니다. 3a단계와 3b단계에서는 보고 상태의 두 가지 일반적인 오류인 누락된 필드 오류와 부정확한 오류를 다룹니다.
3a단계: '필드 누락' 오류
'필드 누락' 오류는 특정 기기의 QUERY 응답과 보고된 상태 요청 간에 페이로드 필드 집합이 다른 경우에 발생합니다. 각 기기의 페이로드 내 필드 집합은 동일해야 합니다. 이는 페이로드를 계산하는 로직이 쿼리와 보고 상태 응답 간에 다른 경우에 발생할 수 있습니다. 아래 차트를 사용하여 쿼리 및 보고 상태 응답이 일치하지 않는 기기 유형과 특성을 추적하세요.
3b단계: '부정확함' 오류
부정확한 오류는 특정 기기의 QUERY 응답과 보고된 상태 요청 간에 페이로드 필드 집합이 동일하지만 상태 값이 다른 경우에 발생합니다. 상태 보고서가 누락되었거나 상태를 계산하는 로직이 쿼리와 상태 보고서 간에 다른 경우 이러한 문제가 발생할 수 있습니다. 아래 차트를 사용하여 쿼리 및 보고 상태 응답이 일치하지 않는 기기 유형과 특성을 추적하세요.
6. 기타 문서 및 리소스
- 이 대시보드에 관한 의견을 보내거나 문제를 신고하려면 공개 Issue Tracker에 문제를 신고하세요.
- 이의신청을 제출하려면 품질 측정항목 이의신청 양식을 사용하여 문제를 신고하세요.
- 통합 품질을 정기적으로 파악하려면 측정항목이 허용 기준 미만으로 떨어질 때 알림을 받도록 Google Cloud Platform 알림을 구성하세요. 이렇게 하면 문제가 발생했을 때 가장 먼저 알 수 있습니다.
- 기타 모든 정보는 개발자 문서(https://developers.home.google.com/tools/analytics/home-vitals)에서 자세히 알아보세요.