1. Antes de comenzar
Este codelab está diseñado para socios y desarrolladores de Google Home con integraciones en la nube para mejorar la calidad del ecosistema y la experiencia del usuario.
Qué aprenderás
El panel de Google Home Vitals es la fuente central de información para que los desarrolladores y socios supervisen el estado operativo de sus integraciones de Google Home. En un ecosistema en el que la experiencia del usuario se define por la latencia y la confiabilidad, Google Home Vitals es el portal de autoservicio que contiene todas las estadísticas detalladas necesarias para pasar de la solución de problemas reactiva a la administración proactiva de la calidad.
- Cómo se calcula tu puntuación de integración de calidad
- Cómo leer y usar el panel
- Cómo depurar métricas de baja calidad
Requisitos
- Tener una integración en la nube de Google Home
Configuración
Sigue estos pasos para navegar al panel de Vitals de Google Home:
- Abre Google Cloud Platform
- Monitoring > Panel
- Haz clic en el panel de Google Home Vitals (Cloud).
2. Cómo leer el panel
Cálculo del nivel de calidad: Estándar "Bueno" vs. "Deficiente"
En el panel, se explica el desglose de la calificación de calidad. Los niveles de calidad se asignan con un nivel de detalle del tipo de dispositivo. Para que una integración de tipo de dispositivo se considere BUENA, debe cumplir con cuatro criterios simultáneos:
- Tasa de éxito global: La tasa de éxito general de las llamadas de socio a Google debe ser >=99.5%.
Nota: Si no se cumple con la tasa de éxito global (>=99.5%), se asignará automáticamente una calificación de DEFICIENTE en todo el proyecto, independientemente del rendimiento de cada dispositivo. - Confiabilidad de los comandos: Las tasas de éxito de QUERY y EXECUTE deben ser mayores o iguales al 99.5% para cada tipo de dispositivo.
- Latencia de respuesta: La latencia del percentil 90 para QUERY y EXECUTE debe ser <=1,000 ms para cada tipo de dispositivo.
- Integridad del estado: La precisión del estado debe ser mayor o igual al 99.5%.
Por qué son importantes estas métricas
- Tasa de éxito global: Las llamadas del socio a Google a nivel de la integración miden el estado de las llamadas de tu nube a Google. Una tasa de éxito superior al 99.5% garantiza que Google Home use los estados correctos del dispositivo. Algunos ejemplos incluyen asegurarse de que se agreguen y quiten dispositivos, de que se activen las automatizaciones y de que los eventos del historial aparezcan en la pestaña Actividad de la app de Google Home.
- Confiabilidad de los comandos: Las tasas de éxito de QUERY y EXECUTE se miden a nivel del tipo de dispositivo.Una tasa de éxito superior al 99.5% garantiza que los comandos del usuario se cumplan correctamente (es decir, evita respuestas del Asistente como "No puedo acceder al dispositivo" o la confirmación incorrecta de un comando que no se cumplió).
- Latencia de respuesta: Las latencias de QUERY y EXECUTE también se miden a nivel del tipo de dispositivo. Una latencia de <=1,000 ms por tipo de dispositivo garantiza que el usuario no tenga que esperar demasiado para realizar la acción deseada (es decir, esperar unos segundos para que se apague la luz).
- Integridad del estado: La métrica de precisión del estado mide la exactitud del estado almacenado en los sistemas de Google y que se usa para entregar las búsquedas de los usuarios. Si estos números son bajos, es posible que los usuarios vean resultados incorrectos para tus dispositivos cuando consulten el estado de tu dispositivo o usen funciones basadas en IA, como Pregúntale a Home. Es posible que las automatizaciones no se activen y que las entradas del historial no aparezcan en Actividad en el momento adecuado.
Cómo leer el panel
Comienza en la sección Métricas del nivel de calidad, que funciona como el indicador de estado principal de tu integración. Una calificación BUENA a nivel del dispositivo depende de que todas las métricas de esta sección cumplan con los criterios de éxito VERDE. En la documentación del Developer Center, se encuentran disponibles los requisitos técnicos detallados y las definiciones de las métricas.
La sección "Puntuación de métricas de calidad" que se encuentra en la parte superior del panel de Google Home Vitals refleja las métricas que se usan para calcular la puntuación de calidad de tu integración.
Leyenda
- VERDE (BUENO): La métrica cumple con el umbral de calidad.
- ROJO (DEFICIENTE): La métrica no cumple con el umbral de calidad.
Ejemplo
En el siguiente ejemplo, puedes ver que el tipo de dispositivo AC_UNIT cumple con los criterios de calidad en la tasa de éxito de QUERY y EXECUTE, así como en la sección de latencia de QUERY, pero no cumple con la barra de latencia de EXECUTE (roja). Esto significa que los comandos se ejecutan correctamente a una tasa de aprobación, pero la latencia de EXECUTE es 36 ms demasiado lenta. La sección Estado del sistema muestra un porcentaje de error del 98.92% para los métodos agregados en toda la integración, lo que significa que hay margen de mejora para garantizar la precisión de los estados de los dispositivos de los usuarios en Google Home. Esto significa que el 1.08% de las llamadas (DeleteAgentUser, Query, ReportStateAndNotification, RequestSyncDevices o Sync) devuelven códigos de respuesta que no son iguales a 2xx o 5xx (p. ej., errores 404). La última métrica que se usa para medir la calidad de aprobación o reprobación del tipo de dispositivo AC_UNIT es la precisión del estado. En este ejemplo, vemos una tasa de éxito del 77.43%, lo que significa que es probable que los usuarios vean resultados inexactos para los dispositivos. Con estas tres métricas, la puntuación general de AC_UNIT es DEFICIENTE y está por debajo del umbral de calidad.
Cada uno de estos cálculos de calidad corresponde a una sección de depuración que se incluye a continuación. Abre los pasos contraídos para depurar aún más.
Para depurar las latencias y las tasas de éxito de QUERY/EXECUTE, ve a "Paso 1: Valida las llamadas a Cloud".
Para depurar los porcentajes de éxito de la comunicación entre el socio y Google, ve a "Paso 2: Valida las llamadas a Google".
Para depurar la precisión del estado de cada tipo de dispositivo, ve a "Paso 3: Mejora la precisión del estado".
3. Paso 1 de la depuración: Valida las llamadas a Cloud
Paso 1: Descripción general
En esta sección, se analizan las llamadas a la nube, es decir, las métricas que miden el estado de las comunicaciones de Google con tu backend en la nube (también conocidas como métricas de Google a socio). Esto incluye comandos como Query y Execute.
Hacemos un seguimiento de las tasas de éxito y las latencias de QUERY y EXECUTE (que influyen en las puntuaciones de calidad de tu tipo de dispositivo).
En el siguiente resumen, se muestran las tasas de éxito y los errores agregados de QUERY y EXECUTE a nivel de la integración. Los pasos del 1a al 1d muestran el desglose de estas métricas a nivel del tipo o rasgo del dispositivo. 
Los pasos 1a y 1b muestran la tendencia del recuento de solicitudes de cumplimiento, los recuentos de errores a lo largo del tiempo y los estados de error específicos.
Paso 1a: Revisa los errores de la consulta
Paso 1b: Revisa los errores de ejecución
En los pasos 1c y 1d, también se muestra el desglose del percentil 90 y el percentil 50 para estas métricas, tanto a nivel de la integración como a nivel del tipo de dispositivo.
Paso 1c: Revisa la latencia de la búsqueda
Paso 1d: Revisa la latencia de ejecución
4. Depuración, paso 2: Valida las llamadas a Google
Paso 2: Descripción general
Después de depurar las llamadas de Google al socio, este segundo paso abarca la depuración de las llamadas de la nube del socio a Google. En esta sección, se abarcan las métricas a nivel de la integración del socio, no a nivel del tipo de dispositivo. Esto incluye códigos de respuesta como 400 Bad Request, 404 Not Found y 429 Resource Exhausted.
Paso 2a: Depura problemas de cuota
Google Home limita el uso y la asignación de recursos, y aplica las cuotas correspondientes a cada proyecto. Google aplica el límite predeterminado de 6,000 solicitudes por 60 segundos al agregado de tus llamadas a la API de consultas, eliminación, Report State y sincronización de solicitudes asíncronas, por cada integración de Cloud a Cloud.
Los problemas relacionados con el límite de cuota pueden afectar negativamente la precisión del estado del informe, ya que no completar una actualización de estado puede causar una discrepancia. A continuación, se muestran gráficos con desgloses que muestran específicamente el estado del informe y los errores de sincronización de solicitudes, el desglose del método de la API de recuento y errores, así como el porcentaje de uso de la cuota. Si estos gráficos muestran un aumento inesperado en el tráfico, revisa tu integración para determinar si un cambio está provocando que se envíe más tráfico a la API de Home Graph.
En algunas situaciones, como el crecimiento natural del tráfico con el tiempo (p. ej., el crecimiento es coherente con un aumento en la cantidad de dispositivos, el lanzamiento de un nuevo tipo de dispositivo o algún otro lanzamiento esperado), puede ser apropiado aumentar la cuota de tu integración. Para solicitar un aumento de la cuota, sigue los pasos que se indican en nuestra documentación para desarrolladores.
5. Depuración, paso 3: Mejora la precisión del estado
Paso 3: Descripción general
Una vez que se depuraron el paso 1 y el paso 2, el paso 3 abarca la precisión de Report State, los estados del dispositivo almacenados en los sistemas de Google que se usan para responder las búsquedas de los usuarios. A continuación, se muestran los desgloses por rasgo y tipo de dispositivo. Los pasos 3a y 3b abarcan dos errores comunes de Report State: errores de campo faltante y errores de imprecisión.
Paso 3a: Errores de "Falta el campo"
Los errores de "Falta un campo" se producen cuando el conjunto de campos de carga útil difiere entre una respuesta de QUERY y una solicitud de estado informado para un dispositivo determinado. El conjunto de campos dentro de la carga útil de cada dispositivo debe ser el mismo. Esto puede ocurrir si la lógica para calcular la carga útil difiere entre su respuesta de estado de QUERY y de informe. Usa los gráficos a continuación para rastrear qué tipos y rasgos de dispositivos tienen respuestas de estado de QUERY y de informes que no coinciden.
Paso 3b: Errores de "inexactitud"
Los errores imprecisos se producen cuando el conjunto de campos de carga útil es el mismo entre una respuesta de QUERY y una solicitud de estado informado para un dispositivo determinado, pero los valores de estado difieren. Esto puede ocurrir si se omite un informe de estado o si la lógica para calcular el estado difiere entre QUERY y un informe de estado. Usa los gráficos a continuación para rastrear qué tipos y rasgos de dispositivos tienen respuestas de estado de QUERY y de informes que no coinciden.
6. Otros recursos y documentación
- Para enviar comentarios o informar problemas relacionados con este panel, registra un problema en nuestro Issue Tracker público.
- Para presentar una solicitud de apelación, registra un problema con nuestro formulario de apelación de métricas de calidad.
- Para mantenerte al tanto de la calidad de tu integración, configura alertas de Google Cloud Platform para recibir notificaciones cuando tus métricas estén por debajo de un umbral aceptable. Esto garantiza que seas la primera persona en saber cuando surja un problema.
- Para obtener más información, consulta la documentación para desarrolladores en https://developers.home.google.com/tools/analytics/home-vitals.