OpenCensus es un proyecto gratuito de código abierto cuyas bibliotecas:
- Proporciona asistencia independiente del proveedor para la recopilación de datos de seguimiento y de métricas en varios idiomas.
- Puede exportar los datos recopilados a varias aplicaciones de backend, incluida Cloud Monitoring, mediante el uso de exportadores.
Aunque Cloud Monitoring proporciona una API que admite la definición y recopilación de métricas personalizadas, es una API patentada de bajo nivel. OpenCensus proporciona una API que sigue el estilo de la comunidad de lenguajes, junto con un exportador que envía tus datos de métricas a Cloud Monitoring a través de la API de Monitoring.
OpenCensus también tiene una buena asistencia para el seguimiento de aplicaciones; consulta Seguimiento de OpenCensus a fin de obtener una descripción general. Cloud Trace recomienda que uses OpenCensus para la instrumentación de seguimiento. Para recopilar datos de métricas y de seguimiento de tus servicios, puedes usar una sola distribución de bibliotecas. Si quieres obtener información sobre el uso de OpenCensus con Cloud Trace, consulta Bibliotecas cliente para Trace.
Antes de comenzar
Para usar Cloud Monitoring, debes tener un proyecto de Cloud con la facturación habilitada. Si es necesario, haz lo siguiente:
-
En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.
- Asegúrate de que la API de Monitoring esté habilitada. Para obtener más información, consulta Habilita la API de Monitoring.
Para las aplicaciones que se ejecutan fuera de Google Cloud, tu proyecto de Cloud debe autenticar tu aplicación. Por lo general, la autenticación se crea mediante la creación de una cuenta de servicio para tu proyecto y la configuración de una variable de entorno.
Para las aplicaciones que ejecutas en una instancia de Amazon Elastic Compute Cloud (Amazon EC2), crea la cuenta de servicio para el proyecto de conector de AWS de la instancia.
Para obtener información sobre cómo crear una cuenta de servicio, consulta Comienza a usar la autenticación.
Instala OpenCensus
Para usar las métricas recopiladas por OpenCensus en tu proyecto de Google Cloud, debes hacer que las bibliotecas de métricas de OpenCensus y el exportador de Stackdriver estén disponibles para tu aplicación. El exportador de Stackdriver exporta las métricas que OpenCensus recopila a tu proyecto de Google Cloud. Luego, puedes usar Cloud Monitoring para graficar o supervisar esas métricas.
Go
Usar OpenCensus requiere la versión 1.11 de Go o una superior. Las dependencias se administran de forma automática.
Java
Para Maven, agrega lo siguiente al elemento
dependencies
en tu archivo pom.xml
:
Node.js
- Antes de instalar las bibliotecas centrales y de exportador de OpenCensus, asegúrate de haber preparado tu entorno para el desarrollo de Node.js.
- La forma más fácil de instalar OpenCensus es con npm:
npm install @opencensus/core npm install @opencensus/exporter-stackdriver
- Coloca las declaraciones
require
que se muestran a continuación en la parte superior de la secuencia de comandos principal o punto de entrada de tu aplicación antes de colocar cualquier otro código:
Python
Instala las bibliotecas principales de OpenCensus y del exportador de Stackdriver con el siguiente comando:
pip install -r opencensus/requirements.txt
El archivo requirements.txt
está en el repositorio de GitHub para estos ejemplos, python-docs-samples.
Escribe métricas personalizadas con OpenCensus
Instrumentar tu código a fin de usar OpenCensus para métricas implica tres pasos:
- Importa las estadísticas de OpenCensus y los paquetes del exportador de Stackdriver para OpenCensus.
- Inicializa el exportador de Stackdriver.
- Usa la API de OpenCensus para instrumentar tu código.
El siguiente ejemplo es un programa mínimo que escribe datos de métricas con OpenCensus. El programa ejecuta un bucle y recopila medidas de latencia. Cuando el bucle finaliza, exporta las estadísticas a Cloud Monitoring y sale:
Go
Java
Node.js
Python
El programa crea una vista de OpenCensus que se llama task_latency_distribution
. Esta string se convierte en parte del nombre de la métrica cuando se exporta a Cloud Monitoring. Consulta Recupera descriptores de métricas para ver cómo se realiza la vista de OpenCensus como un descriptor de métrica de Cloud Monitoring.
A continuación, puedes usar el nombre de la vista como una string de búsqueda cuando seleccionas una métrica para representar.
- En Google Cloud Console, ve a la página Explorador de métricas en Monitoring.
- En la barra de herramientas, selecciona la pestaña Explorador.
- Selecciona la pestaña Configuración.
- Expande el menú Seleccionar una métrica, ingresa
OpenCensus/task_latency_distribution
en la barra de filtros y, luego, usa los submenús para seleccionar una métrica y un tipo de recurso específicos:- En el menú Recursos activos, selecciona el recurso supervisado. Si ejecutas el programa en un entorno local, selecciona Global.
- En el menú Categorías de métricas activas, selecciona Personalizadas.
- En el menú Métricas activas, selecciona Distribución de latencia de las tareas.
- Haz clic en Aplicar.
- Opcional: Para configurar cómo se visualizan los datos, agrega filtros y usa los menús Agrupar por, Agregador y tipo de gráfico. Para este gráfico, expande el menú Line chart y, luego, selecciona Heatmap chart. Para obtener más información, consulta Selecciona métricas cuando uses el Explorador de métricas.
- Opcional: Cambia la configuración del gráfico:
- Para obtener cuotas y otras métricas que informen una muestra por día, establece el período en al menos una semana y el tipo de trazado en Gráfico de barras apiladas.
- Para las métricas con valor de distribución, establece el tipo de trazado en Gráfico de mapa de calor.
En la siguiente captura de pantalla, se muestra la serie temporal recopilada después de ejecutar el programa en un entorno local:
Cada barra en el mapa de calor representa una ejecución del programa, y los componentes en colores de cada barra representan depósitos en la distribución de latencia.
Lee las métricas de OpenCensus en Cloud Monitoring
Usas métricas personalizadas, incluidas las que escribe OpenCensus, como las métricas integradas. Puedes graficarlas, configurar alertas, leerlas y supervisarlas.
En esta sección, se ilustra cómo usar el Explorador de API para leer datos de métricas. Para obtener información sobre cómo leer datos de métricas mediante la API de Cloud Monitoring o las bibliotecas cliente, consulta los siguientes documentos:
- En Métricas de navegación, se explica cómo enumerar y examinar tus métricas personalizadas y también integradas.
- En Métricas de lectura, se explica cómo recuperar datos de series temporales de métricas integradas y personalizadas con la API de Monitoring.
Por ejemplo, la captura de pantalla que se muestra en la sección anterior es del Explorador de métricas. Cuando uses las herramientas de gráficos, te recomendamos que uses el nombre de la vista de OpenCensus para filtrar la lista de métricas. Para obtener más información, consulta Selecciona métricas cuando uses el Explorador de métricas.
Recupera descriptores de métricas
Para recuperar los datos de las métricas directamente mediante la API de Monitoring, debes conocer los nombres de Cloud Monitoring a los que se exportaron las métricas de OpenCensus. Para determinar estos nombres, puedes recuperar los descriptores de métricas que crea el exportador y, luego, observar el campo type
. Para obtener detalles sobre los descriptores de métricas, consulta MetricDescriptor
.
Para ver los descriptores de métricas creados para las métricas exportadas, haz lo siguiente:
- Ve a la página de referencia de
metricDescriptors.list
. En el widget Prueba esta API en la página de referencia, completa los siguientes campos:
Ingresa el nombre de tu proyecto en el campo
name
. Usa la siguiente estructura de nombre:projects/PROJECT_ID
. En este documento, se usa un proyecto con el IDa-gcp-project
.Ingresa un filtro en el campo
filter
. Hay muchos descriptores de métricas en un proyecto. El filtrado te permite eliminar aquellos descriptores que no son de interés.Por ejemplo, debido a que el nombre de la vista de OpenCensus se convierte en parte del nombre de la métrica, puedes agregar un filtro como este:
metric.type=has_substring("task_latency_distribution")
La clave
metric.type
es un campo en un tipo incorporado en una serie temporal. ConsultaTimeSeries
para obtener más detalles.Haz clic en Ejecutar.
A continuación, se muestra el descriptor de métrica mostrado:
{ "metricDescriptors": [ { "name": "projects/a-gcp-project/metricDescriptors/custom.googleapis.com/opencensus/task_latency_distribution", "labels": [ { "key": "opencensus_task", "description": "Opencensus task identifier" } ], "metricKind": "CUMULATIVE", "valueType": "DISTRIBUTION", "unit": "ms", "description": "The distribution of the task latencies", "displayName": "OpenCensus/task_latency_distribution", "type": "custom.googleapis.com/opencensus/task_latency_distribution" } ] }
Esta línea en el descriptor de métrica te indica el nombre del tipo de métrica en Cloud Monitoring:
"type": "custom.googleapis.com/opencensus/task_latency_distribution"
Ahora tienes la información que necesitas para recuperar de forma manual los datos asociados con el tipo de métrica. El valor del campo type
también se muestra en Google Cloud Console cuando graficas la métrica.
Recuperar datos de métricas
Para recuperar manualmente datos de series temporales de un tipo de métrica, haz lo siguiente:
- Ve a la página de referencia de
timeSeries.list
. En el widget Prueba esta API en la página de referencia, completa los siguientes campos:
- Ingresa el nombre de tu proyecto en el campo
name
. Usa la siguiente estructura de nombre:projects/PROJECT_ID
. En el campo
filter
, ingresa el siguiente valor:metric.type="custom.googleapis.com/opencensus/task_latency_distribution"
Ingresa los valores para los campos
interval.startTime
yinterval.endTime
. Estos valores se deben ingresar como una marca de tiempo, por ejemplo,2018-10-11T15:48:38-04:00
. Asegúrate de que el valorstartTime
sea anterior al valorendTime
.Haga clic en el botón Execute.
- Ingresa el nombre de tu proyecto en el campo
A continuación, se muestra el resultado de la recuperación:
{ "timeSeries": [ { "metric": { "labels": { "opencensus_task": "java-3424@docbuild" }, "type": "custom.googleapis.com/opencensus/task_latency_distribution" }, "resource": { "type": "gce_instance", "labels": { "instance_id": "2455918024984027105", "zone": "us-east1-b", "project_id": "a-gcp-project" } }, "metricKind": "CUMULATIVE", "valueType": "DISTRIBUTION", "points": [ { "interval": { "startTime": "2019-04-04T17:49:34.163Z", "endTime": "2019-04-04T17:50:42.917Z" }, "value": { "distributionValue": { "count": "100", "mean": 2610.11, "sumOfSquaredDeviation": 206029821.78999996, "bucketOptions": { "explicitBuckets": { "bounds": [ 0, 100, 200, 400, 1000, 2000, 4000 ] } }, "bucketCounts": [ "0", "0", "1", "6", "13", "15", "44", "21" ] } } } ] }, [ ... data from additional program runs deleted ...] ] }
Los datos de métricas que se muestran incluyen los siguientes:
- Información acerca del recurso supervisado sobre el cual se recopilaron los datos.
OpenCensus puede detectar de forma automática los recursos supervisados
gce_instance
,k8s_container
yaws_ec2_instance
. Estos datos provienen de un programa que se ejecuta en una instancia de Compute Engine. Para obtener información sobre el uso de otros recursos supervisados, consulta Establece recursos supervisados para el exportador. - Descripción de la clase de métrica y el tipo de los valores.
- Los datos reales recopilados dentro del intervalo de tiempo solicitado.
Cómo representa Monitoring las métricas de OpenCensus
Se admite el uso directo de la API de Cloud Monitoring para las métricas personalizadas; su uso se describe en Crea métricas personalizadas con la API. De hecho, el exportador de OpenCensus para Cloud Monitoring usa esta API. En esta sección, se proporciona información sobre cómo Cloud Monitoring representa las métricas que escribe OpenCensus.
Las construcciones que usa la API de OpenCensus difieren de las construcciones que usa Cloud Monitoring; lo mismo sucede con algunos usos de la terminología. Donde Cloud Monitoring hace referencia a “métricas”, OpenCensus algunas veces hace referencia a “estadísticas”. Por ejemplo, el componente de OpenCensus que envía datos de métricas a Cloud Monitoring se denomina “exportador de estadísticas para Stackdrdiver”.
Si deseas obtener una descripción general del modelo de OpenCensus para métricas, consulta Métricas de OpenCensus.
Los modelos de datos para las estadísticas de OpenCensus y las métricas de Cloud Monitoring no pertenecen a una asignación de 1:1. Muchos de los mismos conceptos existen en cada uno, pero no son directamente intercambiables.
Una vista de OpenCensus es análoga a
MetricDescriptor
en la API de Monitoring. Una vista describe cómo recopilar y agregar mediciones individuales. Las etiquetas se incluyen en todas las mediciones registradas.Una etiqueta de OpenCensus es un par clave-valor. Por lo general, una etiqueta de OpenCensus corresponde al
LabelDescriptor
en la API de Monitoring. Las etiquetas te permiten capturar información contextual que puedes usar para filtrar y agrupar métricas.Una medida de OpenCensus describe datos de métricas para registrar. Una agregación de OpenCensus es una función que se aplica a los datos que se usan para resumirla. Estas funciones se usan en la exportación para determinar
MetricKind
,ValueType
y la unidad informada en el descriptor de métrica de Cloud Monitoring.Una medición de OpenCensus es un dato recopilado. Las mediciones deben ser agregadas en vistas. De lo contrario, las mediciones individuales se descartan. Una medición de OpenCensus es análoga a un
Point
en la API de Monitoring. Cuando las mediciones se agregan en las vistas, los datos agregados se almacenan como datos para la visualización, análogos aTimeSeries
en la API de Monitoring.
¿Qué sigue?
OpenCensus proporciona la documentación de referencia autorizada para tu API de métricas y el exportador de Stackdriver. La siguiente tabla proporciona vínculos a estos documentos de referencia:
Lenguaje Documentación de referencia de la API Documentación del exportador Guía de inicio rápido Comienza a usarlo API de Go Exportadores de seguimiento y estadísticas Métricas Java API de Java Exportador de estadísticas Métricas NodeJS API de NodeJS Exportador de estadísticas Métricas Python API de Python Exportador de estadísticas Métricas