El seguimiento de OpenTelemetry te permite identificar y hacer un seguimiento de la latencia de varias operaciones de la biblioteca cliente de Pub/Sub, como el procesamiento por lotes, la administración de asignaciones y el control de flujo. La recopilación de esta información puede ayudarte a depurar problemas de la biblioteca cliente.
Estos son algunos casos de uso potenciales para el seguimiento de OpenTelemetry:
- Tu servicio está experimentando una latencia de publicación más alta de lo normal.
- Estás experimentando una gran cantidad de reenvío de mensajes.
- Un cambio en la función de devolución de llamada del cliente de suscriptor hace que el procesamiento tarde más de lo habitual.
Antes de comenzar
Antes de configurar OpenTelemetry, completa las siguientes tareas:
- Configura Pub/Sub con una de las bibliotecas cliente.
- Instala el SDK de OpenTelemetry. y configura un exportador de seguimiento y un proveedor de rastreadores.
- Habilita la API de Cloud Trace.
- Obtén información para leer los seguimientos de la Observabilidad de Cloud.
Roles obligatorios
Para garantizar que la cuenta de servicio tenga permisos para exportar seguimientos a Cloud Trace, solicita a tu administrador que otorgue el acceso los siguientes roles de IAM en tu proyecto:
-
Todos:
Agente de Cloud Trace (
roles/cloudtrace.agent
)
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
Estos roles predefinidos contienen los permisos necesarios para exportar registros a Cloud Trace. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:
Permisos necesarios
Se requieren los siguientes permisos para exportar seguimientos a Cloud Trace:
-
Todos:
cloudtrace.traces.patch
Es posible que tu administrador también pueda otorgar estos permisos a la cuenta de servicio con roles personalizados o con otros roles predefinidos.
Flujo de trabajo de seguimiento de OpenTelemetry
Para configurar el seguimiento de OpenTelemetry, usa las bibliotecas cliente de Pub/Sub y el SDK de OpenTelemetry. Con el SDK, debes configurar un un exportador de seguimiento y un proveedor de rastreadores, antes de las bibliotecas de Pub/Sub. En algunas bibliotecas, configurar un proveedor de generadores de registros es opcional.
Exportador de Trace. El SDK de OpenTelemetry usa el exportador de seguimientos para determinar dónde enviar los seguimientos.
Proveedor del rastreador. Las bibliotecas cliente de Pub/Sub usan el rastreador proveedor para crear seguimientos.
En los siguientes pasos, se describe cómo configurar el seguimiento:
- Crea una instancia de un exportador de OpenTelemetry de Cloud Trace.
- Si es necesario, crea una instancia y regístralo de un proveedor de rastreadores con el SDK de OpenTelemetery.
- Configura tu cliente con la opción de habilitar el seguimiento de OpenTelemetry.
- Usa las bibliotecas cliente de Pub/Sub para publicar un mensaje.
Cómo funciona el seguimiento
Para cada mensaje publicado, la biblioteca cliente crea un registro nuevo. Este seguimiento representa todo el ciclo de vida del mensaje, desde el momento en que publicas un cuando se confirma la recepción. Un seguimiento encapsula información como la duración de las operaciones, los intervalos superiores y secundarios, y los intervalos vinculados.
Un seguimiento se compone de un intervalo raíz y sus intervalos secundarios correspondientes. Estos intervalos representan el trabajo que realiza la biblioteca cliente cuando procesa un mensaje. Cada registro de mensajes contiene lo siguiente:
- Para publicación. Control de flujo, programación de claves de orden, procesamiento por lotes y la longitud de la RPC de publicación
- Para suscripciones. Control de simultaneidad, programación de claves de orden y administración de arrendamientos
Para propagar información desde el lado de publicación hasta el lado de suscripción, el
Las bibliotecas cliente insertan un atributo específico de seguimiento en el método Publication
lado derecho. El mecanismo de propagación de contexto solo se habilita cuando se activa el seguimiento
y está precedido por el prefijo googclient_
.
Publica mensajes con seguimiento
En la siguiente muestra de código, se indica cómo habilitar el seguimiento con la Biblioteca cliente de Pub/Sub y el SDK de OpenTelemetry. En este ejemplo, los resultados del seguimiento se exportan a Cloud Trace.
Consideraciones
Cuando creas una instancia del proveedor de generador de registros, configuras una proporción de muestreo con el SDK de OpenTelemetry. Esta proporción determina cuántos seguimientos debe muestrear el SDK. Una tasa de muestreo más baja puede ayudar a reducir los costos de facturación y evitar que tu servicio supere la cuota de intervalo de Cloud Trace.
Go
C++
Python
Antes de probar esta muestra, sigue las instrucciones de configuración de Python en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Python.
TypeScript
Node.js
Recibe mensajes con seguimiento
Go
C++
Python
TypeScript
Node.js
Cómo analizar un registro
En las siguientes secciones, se incluye información detallada sobre cómo hacer un seguimiento de un seguimiento y analizarlo en la consola de Google Cloud.
Consideraciones
- Al publicar un lote de mensajes, el intervalo de RPC de publicación se captura en un seguimiento separado.
- Una RPC de publicación tiene varios intervalos de origen, ya que varias llamadas de creación pueden generar una RPC de publicación cuando se agrupan.
Los intervalos de OpenTelemetry pueden tener uno o cero intervalos superiores.
Los intervalos que representan operaciones por lotes, como un lote de publicación (que, lógicamente, debería tener varios elementos superiores), no se pueden representar con cero o un intervalo superior.
Realiza un seguimiento de los intervalos creados durante el ciclo de vida del mensaje
En la siguiente imagen, se muestra un ejemplo de los intervalos que se crean en un solo seguimiento para un solo mensaje.
Cada intervalo puede tener atributos adicionales que proporcionan información adicional, como el tamaño de bytes del mensaje y la información de la clave de orden.
Los atributos de intervalo transmiten metadatos adicionales, como la clave de ordenamiento del mensaje, el ID del mensaje y el tamaño del mensaje.
Los intervalos de publicación y suscripción principales se aumentan con eventos de intervalo que corresponden al momento en que se emite una llamada de red y cuando se completa.
Soluciona los problemas comunes.
Los siguientes problemas pueden causar problemas con el seguimiento:
- La cuenta de servicio que usas para exportar registros no tiene el rol
roles/cloudtrace.agent
requerido. - Se alcanzó la cuota de la cantidad máxima de intervalos transferidos en Cloud Trace.
- Tu aplicación se cierra sin llamar a la función de limpieza adecuada.