Google Home Vitals (클라우드)

이 대시보드 및 알림 모음을 사용하면 Google Home 생태계와의 고품질 통합을 선제적으로 유지할 수 있습니다. Google은 파트너가 모든 고객을 위한 고품질 생태계를 개발할 수 있도록 지원하기 위해 최선을 다하고 있습니다.

대시보드에는 세 가지 섹션이 있으며, 각 섹션은 전체 통합 품질에 기여하는 핵심 부분을 다룹니다.

1. Google에서 파트너로의 측정항목 - Google에서 클라우드 백엔드로의 호출 상태를 측정합니다.

2. 시스템 상태 - 파트너에서 Google로의 측정항목 - 시스템에서 Google로의 호출 상태를 측정합니다.

3. 기기 상태 - 상태 정확성 - Google 시스템에 저장된 상태의 정확성을 측정합니다. 이 상태는 사용자 쿼리를 처리하는 데 사용됩니다.

측정항목이 목표 값을 충족하지 못하면 사용자 환경에 영향을 줄 수 있는 문제를 나타내기 위해 빨간색으로 강조표시됩니다. 다음 정보는 각 타겟과 이것이 사용자에게 중요한 이유에 관한 세부정보를 제공합니다.

다음 버튼을 눌러도 대시보드로 바로 이동하지 않는 경우 개요 페이지를 선택하고 대시보드를 선택한 다음 내 대시보드 목록에서 Google Home Vitals 대시보드 (Cloud)를 선택하여 대시보드를 확인합니다.

대시보드로 이동

Google에서 파트너로의 측정항목

쿼리/실행 성공률 >= 99.5% 측정항목은 사용자의 명령어가 얼마나 자주 올바르게 처리되는지 측정합니다. 이를 통해 '기기에 연결할 수 없습니다'와 같은 어시스턴트 응답을 방지하거나 아직 처리되지 않은 명령어를 잘못 확인하는 것을 방지할 수 있습니다.

동기화 성공률 >= 99.5% 측정항목은 동기화 요청이 올바르게 처리되는 빈도를 측정하여 Google Home에 표시된 기기가 클라우드 인프라에 연결된 기기와 동기화되도록 합니다.

'성공'의 정의는 무엇인가요?

Google Home 플랫폼에서 의도한 작업이 처리되었거나 요청된 상태가 검색되었음을 나타내는 유효한 응답을 수신하면 트랜잭션이 성공으로 표시됩니다.

비차단 예외가 포함된 응답 (예: lowBattery 예외가 수반되는 SUCCESS 상태)은 성공적인 트랜잭션으로 계산됩니다. 명령어가 기기에 도달했으며 경고에도 불구하고 인텐트가 충족되었습니다.

'실패'는 어떻게 정의되나요?

일반적인 플랫폼 오류 코드에서 발견된 오류 중 파트너가 조치 가능으로 표시된 오류는 QUERY, EXECUTE, SYNC 성공률을 계산할 때 '실패'로 간주됩니다. 또한 오류 및 예외에서 발견된 오류도 '실패'이며 다음과 같은 예외가 있습니다.

실행 응답 상태 유사성

EXECUTE 응답에서 SUCCESS 상태를 반환할 때 응답 페이로드의 states 객체에는 실행 중인 특성으로 정의된 모든 활성 및 업데이트된 상태 필드가 포함되어야 합니다. 필수 상태 필드를 생략하거나 복잡한 특성에 대해 빈 states 객체를 반환하면 Google Home 플랫폼에서 실행 결과를 파싱하지 못하여 AGENT_ISSUE 또는 INVALID_RESPONSE 실패로 등록되어 쿼리 및 실행 성공률이 떨어집니다.

쿼리/실행 지연 시간(p90) <= 1000ms 측정항목은 요청된 작업 대기 시간을 측정하며 사용자가 너무 오래 기다리지 않도록 합니다(예: 조명이 꺼질 때까지 몇 초 동안 기다림).

지연 시간 측정항목

지연 시간은 최종 사용자에게 통합이 얼마나 반응성이 좋은지 보여주는 중요한 지표입니다. 대시보드는 '가장 느린' 사용자의 경험을 나타내는 90번째 백분위수 (P90) 지연 시간을 추적합니다 (예: P90이 800ms이면 요청의 90% 가 800ms 이내에 확인됨).

Google은 기술적 정확성을 보장하기 위해 상태 확인과 기기 명령어의 지연 시간을 다르게 측정합니다.

1. 쿼리 지연 시간 (질문)

이는 Google에서 기기의 현재 상태를 요청할 때의 Cloud-to-cloud 왕복 시간을 측정합니다.

• 시작: Google에서 처리 URL로 action.devices.QUERY 요청을 전송합니다.
• 측정 기간: 클라우드가 전체 HTTP 응답을 수신, 처리, Google로 다시 전송하는 데 걸리는 시간입니다.
• 종료: Google이 서비스에서 최종 응답 페이로드를 수신하고 확인합니다.

2. EXECUTE 지연 시간 (작업)

Google에서 기기에 제어 요청을 보낼 때 명령어 확인 시간을 측정합니다.

• 시작: Google에서 처리 URL에 action.devices.EXECUTE 요청을 전송합니다.
• 측정 기간: 클라우드가 명령어를 수신하고 확인 응답을 반환하는 데 걸리는 시간입니다.
• 종료: Google이 SUCCESS, PENDING 또는 OFFLINE 상태 응답을 수신합니다.
• 기술 범위: 이 측정항목은 Google 클라우드와 고객 클라우드 간의 '응답 확인' 시간을 측정합니다. 물리적 하드웨어 (예: 전구)가 물리적 상태 변경을 완료하는 데 걸리는 시간은 측정하지 않습니다. 여기에는 클라우드 간 경로 외부의 로컬 메시 네트워크 지연 시간이 포함되는 경우가 많기 때문입니다.

EXECUTE/QUERY 지연 시간 타임라인 분석

EXECUTE 또는 QUERY 지연 시간의 타임스탬프를 분석할 때 총 왕복 시간은 다음과 같은 순차적 흐름으로 세분화할 수 있습니다.

이 분석은 Google 측과 파트너 측 타임스탬프를 비교하므로 파트너 서버는 NTP (네트워크 시간 프로토콜)와 동기화되어야 합니다. 약간의 클록 드리프트 (50~100ms)라도 계산된 운송 기간 (t2 - t1 및 t4 - t3)을 왜곡하여 음수 전송 지연 시간과 같이 논리적으로 불가능한 측정항목이 발생할 수 있습니다.

[t1] 요청 전송됨 (Google 아웃바운드): Google에서 의도 요청을 시작합니다. t1는 직접 노출되지 않으므로 최종 인바운드 타임스탬프에서 총 지연 시간을 빼서 대략적으로 계산됩니다.

네트워크 전송 (t1~t2): 처리 엔드포인트에 도달하기 전의 예상 네트워크 전송 및 대기열 시간입니다.

[t2] 요청 수신 (파트너 인그레스): 요청이 환경의 API Gateway 또는 인그레스 서버에 도착하는 정확한 타임스탬프입니다.

파트너 처리 (t2~t3): 클라우드 환경 내에서 내부 실행, 라우팅, 기기 처리 지연 시간입니다.

[t3] 응답 전송됨 (파트너 이그레스): 서비스에서 처리 응답을 Google에 다시 전송하는 타임스탬프입니다.

반환 전송 (t3~t4): Google로 다시 반환되는 네트워크 라우팅 및 연결 완료 시간입니다.

[t4] 요청 완료 (Google 인바운드): Google이 최종 응답을 수신하고 처리합니다. 이 타임스탬프는 Google Cloud 로그에 receiveTimestamp로 명시적으로 기록됩니다.

이러한 측정항목이 어떻게 연결되는지 보여주기 위해 총 로깅 지연 시간 (latencyMsec)이 1, 700ms이고 Google Cloud receiveTimestamp (t4)가 2026-05-25T15:25:00.550Z인 샘플 EXECUTE 요청을 고려해 보세요.

지연 시간 감소 옵션

지역 라우팅을 위한 아키텍처 권장사항

애니캐스트 IP 구현이 불가능한 경우 사용자가 가장 가까운 리전 데이터 센터에서 서비스를 받을 수 있도록 다음과 같은 비용 효율적인 대안을 사용하는 것이 좋습니다.

1. 전역 부하 분산 (GLB)

   정적 라우팅 대신 전역 애플리케이션 부하 분산기(대부분의 주요 클라우드 제공업체에서 사용 가능)를 사용합니다.

   • 작동 방식: 네트워크 에지에 있는 단일 전역 진입점 (URL)을 구성합니다. 부하 분산기는 Google의 처리 클러스터에서 요청의 지리적 출처를 자동으로 감지하고 트래픽을 가장 가까운 리전의 정상 백엔드로 라우팅합니다.

   • 이점: 구성 복잡성과 비용이 훨씬 적은 Anycast의 성능을 제공합니다.

2. 위치 인식 DNS (GeoDNS)

   • 작동 방식: DNS 쿼리의 지리적 위치에 따라 처리 URL을 다른 IP 주소로 변환하도록 DNS 제공업체를 구성합니다.

   • 구현: DNS 제공업체가 Google의 이그레스 지점에 최적화되어 있는지 확인합니다. Google의 리전별 처리 서비스 (예: 미국, EU, 아시아)가 도메인을 확인하면 해당 특정 리전의 데이터 센터에 대한 IP 주소를 수신합니다.

애플리케이션 계층의 최적화 전략

인프라 수준 라우팅 외에도 애플리케이션 계층에서 다음 전략을 구현하여 요청 처리 지연 시간을 줄일 수 있습니다.

1. '트램펄린' 프록시 메서드

   기본 데이터 센터를 유지해야 하는 경우 리전 경량 프록시 서버 (Trampoline)를 사용하여 초기 핸드셰이크를 처리합니다.

   1. Google이 전역 URL을 호출합니다.

   2. 리전 프록시 (예: 경량 Nginx 또는 Lambda 함수)가 요청을 수신합니다.

   3. 프록시는 내부 고속 백본을 통해 페이로드를 기본 데이터베이스로 전달합니다.

   이점: 장거리 요청의 지연 시간에 가장 큰 영향을 미치는 'TCP 핸드셰이크' 시간이 줄어듭니다.

2. 액세스 토큰 리전 힌트

   계정 연결 (OAuth) 프로세스 중에 시스템은 사용자의 홈 지역을 식별할 수 있습니다.

   구현: Google에 발급된 access_token에 지역 식별자를 인코딩합니다. Google에서 처리 요청을 보내면 게이트웨이는 데이터베이스를 조회할 필요 없이 즉시 토큰을 검사하고 요청을 올바른 리전 클러스터로 라우팅할 수 있습니다.

시스템 상태 - 파트너에서 Google로의 측정항목

성공률이 99.5%이상으로 유지되면 Google Home에서 기기 상태가 올바르고, 기기가 추가 및 삭제되고, 자동화가 트리거되고, 기록 이벤트가 Google Home app (GHA)의 활동 탭에 표시됩니다.

성공률은 클라우드에서 상태 업데이트를 푸시할 때 Google에서 반환하는 HTTP 응답 코드를 기반으로 계산됩니다. Google 측 인프라 문제로 인해 파트너가 불이익을 받지 않도록 이 측정항목은 실패 횟수에서 Google 내부 오류를 제외합니다. 계산에 포함된 API 호출은 HomeGraph API 참조에서 확인할 수 있습니다.

'성공'의 정의는 무엇인가요?

2xx (성공): Home Graph에서 상태 업데이트를 수신하고 처리했습니다.

'실패'는 어떻게 정의되나요?

4xx (파트너 오류)는 실패를 나타내며 클라우드에서 전송된 요청에 문제가 있음을 나타냅니다. 일반적인 코드는 다음과 같습니다.

400 잘못된 요청

원인: 잘못된 문법으로 인해 서버에서 요청을 처리할 수 없습니다. 일반적인 원인으로는 잘못된 형식의 JSON 또는 문자열 값에 "" 대신 null을 사용하는 경우가 있습니다.

해결 방법: 요청 본문이 유효한 JSON인지 확인하고 (문자열 필드에 잘못된 구조나 null 값이 없음) agentUserId가 동기화 응답의 값과 일치하는지 확인합니다.

404 Not Found

원인: HomeGraph에서 deviceId 또는 agentUserId를 찾을 수 없습니다 (아직 동기화되지 않았거나, 이미 연결 해제되었거나, ID가 일치하지 않음).

해결책:

1. agentUserId가 동기화 응답에 제공된 값과 일치하는지 확인합니다.
2. Home Graph SYNC API를 사용하여 404 Not Found 오류가 HomeGraph에서 누락된 기기 또는 사용자로 인해 발생하는지 확인합니다.
3. 기기 또는 계정 추가, 삭제, 이름 바꾸기, 업데이트 후 requestSync를 트리거하여 상태를 최신 상태로 유지해야 합니다.
4. DISCONNECT 인텐트를 적절하게 처리하여 오래된 기기 보고를 중지합니다. DISCONNECT 인텐트를 수신한 후 클라우드 서비스는 동기화 요청 및 상태 보고를 사용하여 Google에 변경사항을 게시하는 것을 중단해야 합니다.

429 리소스 소진

원인: 통합이 할당된 할당량을 초과했습니다.

해결 방법: 할당량 관리 대시보드의 '2a단계: 할당량 문제 디버그' 섹션에 있는 안내를 참조하세요. 자세한 내용은 스마트 홈 할당량 및 한도를 참고하세요.

기기 상태 - 상태 정확성

상태 정확도 99.5%이상을 충족하거나 초과하면 사용자가 기기 상태를 보거나 Home에게 물어보기와 같은 AI 기능을 사용할 때 정확한 결과를 확인할 수 있습니다. 상태 정확도가 낮으면 자동화가 실행되지 않을 수 있으며 기록 항목이 GHA의 활동 탭에 적시에 표시되지 않을 수 있습니다. 자세한 내용은 상태 보고를 참고하세요. 참고: 상태 정확도 목표는 지원되는 모든 특성에서 충족되어야 합니다.

1. 정확성 구성요소

이 측정항목은 Google이 알려진 의도 결과에 대해 보고된 상태를 확인할 수 있는 '샘플'에서 파생됩니다. 기술적 정확성을 위해 정확성은 두 가지 경로를 통해 평가됩니다.

• 쿼리 기반 정확도: 사용자 또는 시스템이 기기의 현재 상태를 적극적으로 조회할 때 확인됩니다.
• EXECUTE 기반 정확성: 제어 요청 후 다시 보고된 명령어 실행 후 기기 상태를 평가하여 확인합니다.

2. 대시보드 측정항목 (시간별 계산)

대시보드는 1시간 간격을 기준으로 정확도를 계산합니다. 통계적 신뢰도를 보장하고 신호가 낮은 노이즈에 대한 통합에 불이익을 주지 않기 위해 Google은 최소 트래픽 양 기준을 적용합니다. 특정 특성과 기기 조합이 5일 연속 기간 동안 총 샘플 수가 100개 미만으로 누적되면 정확도가 통계적으로 유의미하지 않은 것으로 간주되어 해당 사항 없음으로 설정됩니다.

특정 시간대에 두 경로 모두에서 충분한 샘플 볼륨이 있는 경우 특정 상태의 기준 시간당 정확도는 두 독립적인 비율의 평균으로 계산됩니다.

시간별 상태 정확도 = (쿼리 정확도 % + 실행 정확도 %) / 2

각 경로는 다음과 같이 정의됩니다.

• 쿼리 정확도 % = (시간별 정확한 쿼리 샘플) / (시간별 총 쿼리 샘플)
• 실행 정확도 % = (시간당 실행 정확도 샘플) / (시간당 실행 총 샘플)

특성 정확도 점수 (특성별로 계산됨) = SUM(쿼리 정확한 샘플 + 실행 정확한 샘플) / SUM(쿼리 총 샘플 + 실행 총 샘플)

품질 점수는 생태계 전반의 엄격한 최소 실적을 평가하므로 지원되고 자격 요건을 충족하는 모든 특성은 개별적으로 99.5% 이상의 상태 정확도 목표를 충족해야 합니다 (특성 전반의 평균이 아님).

이 뷰는 정확도가 우수한 대량 기기가 소량 기기의 정확도 문제를 가리는 것을 방지합니다. 사용 빈도가 낮은 특성으로 인해 점수가 낮아질까 우려하는 파트너는 사용 빈도가 낮은 특성이 최소 트래픽 양 확인에 의해 자동으로 보호되며, 필요한 샘플 기준을 충족하지 않는 한 최저 유형 및 특성 점수에 반영되지 않는다는 점을 안심할 수 있습니다.

3. 기기 상태 및 상태 정확성 개선

Home Graph에 저장된 상태가 실시간 QUERY의 결과와 일치하지 않으면 불일치가 발생합니다.

'필드 누락' 오류

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

원인: DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD 또는 DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD 오류가 발생하면 동일한 기기의 QUERY 응답과 상태 보고 요청 간에 페이로드 필드 집합이 다릅니다.

해결 방법: 두 경로의 데이터 구조가 동일한지 확인합니다. 특성이 SYNC에 포함된 경우 해당 필드가 사전 대응 보고서와 사후 대응 쿼리 모두에 존재하고 일관되어야 합니다.

'부정확함' 오류

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

원인: DETAILED_ACCURACY_RESULT_INACCURATE 오류의 경우 QUERY 응답에서 반환된 값과 마지막 보고서 상태 값이 일치하지 않습니다.

해결 방법: 기기 상태가 변경될 때마다 Report State가 트리거되고 Report State와 QUERY가 항상 정확히 동일한 최신 값과 모든 필수 필드를 제공하여 데이터 일관성을 유지하도록 합니다.

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

원인: DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE 오류가 발생하면 파트너가 명령어를 성공적으로 실행했지만 업데이트된 기기 상태를 Google에 다시 보고하지 않은 것입니다.

해결 방법: Home Graph가 새 기기 상태를 수신하도록 명령어 실행 후 항상 Report State 업데이트를 전송합니다.

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

원인: DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED 오류의 경우 QUERY 결과가 현재 상태를 제공하지만 이 기기에 대해 수신된 상태 보고가 없습니다 (상태가 비어 있고 보고된 타임스탬프가 에포크에 있음). 이는 상태 업데이트가 트리거되지 않거나, HomeGraph에 도달하지 못하거나, 기기가 연결 또는 운영 상태의 전환을 성공적으로 보고하지 못하고 있음을 나타냅니다.

해결 방법: 모든 상태 변경에 대해 상태 보고가 트리거되고 전송되는지 확인합니다. 백엔드 로직이 상태 업데이트를 올바르게 처리하고, Google HomeGraph에 전송 성공을 확인하고, 기기가 상태를 일관되게 동기화하여 사용자 인터페이스와 자동화 엔진을 정확하게 유지하는지 확인합니다.