Crea métricas personalizadas con OpenCensus

OpenCensus es un proyecto gratuito de código abierto cuyas bibliotecas:

  • Proporciona compatibilidad con un proveedor independiente para la recopilación de datos de métricas y de seguimiento en varios idiomas.
  • Puedes exportar los datos recopilados a varias aplicaciones de backend, incluida Cloud Monitoring, mediante exportadores.

Aunque Cloud Monitoring proporciona una API que admite la definición y recopilación de métricas personalizadas, es una API 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 única 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:

  1. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

    Ir al selector de proyectos

  2. 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.

  3. Asegúrese de que la API de Monitoring esté habilitada. Para obtener más información, consulta Habilita la API de Monitoring.

  4. Para las aplicaciones que se ejecutan fuera de Google Cloud, tu proyecto de Cloud debe autenticar tu aplicación. Por lo general, debes configurar una autenticación para crear una cuenta de servicio en tu proyecto y 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 Cómo comenzar a usar la autenticación.

Instalar 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: 
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-api</artifactId>
  <version>${opencensus.version}</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-impl</artifactId>
  <version>${opencensus.version}</version>
</dependency>
<dependency>
  <groupId>io.opencensus</groupId>
  <artifactId>opencensus-exporter-stats-stackdriver</artifactId>
  <version>${opencensus.version}</version>
</dependency>

Node.js

  1. Antes de instalar las bibliotecas centrales y de exportador de OpenCensus, asegúrate de haber preparado tu entorno para el desarrollo de Node.js.
  2. La forma más fácil de instalar OpenCensus es con npm: 
    npm install @opencensus/core
npm install @opencensus/exporter-stackdriver
  3. 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:
const {globalStats, MeasureUnit, AggregationType} = require('@opencensus/core');
const {StackdriverStatsExporter} = require('@opencensus/exporter-stackdriver');

Python

Instala las bibliotecas centrales de OpenCensus y las bibliotecas de 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 para usar OpenCensus para métricas implica tres pasos:

  1. Importa las estadísticas de OpenCensus y los paquetes del exportador de OpenCensus para Stackdriver.
  2. Inicializa el exportador de Stackdriver.
  3. 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 finaliza el bucle, exporta las estadísticas a Cloud Monitoring y sale:

Go


// metrics_quickstart is an example of exporting a custom metric from
// OpenCensus to Stackdriver.
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"contrib.go.opencensus.io/exporter/stackdriver"
	"go.opencensus.io/stats"
	"go.opencensus.io/stats/view"
	"golang.org/x/exp/rand"
)

var (
	// The task latency in milliseconds.
	latencyMs = stats.Float64("task_latency", "The task latency in milliseconds", "ms")
)

func main() {
	ctx := context.Background()

	// Register the view. It is imperative that this step exists,
	// otherwise recorded metrics will be dropped and never exported.
	v := &view.View{
		Name:        "task_latency_distribution",
		Measure:     latencyMs,
		Description: "The distribution of the task latencies",

		// Latency in buckets:
		// [>=0ms, >=100ms, >=200ms, >=400ms, >=1s, >=2s, >=4s]
		Aggregation: view.Distribution(0, 100, 200, 400, 1000, 2000, 4000),
	}
	if err := view.Register(v); err != nil {
		log.Fatalf("Failed to register the view: %v", err)
	}

	// Enable OpenCensus exporters to export metrics
	// to Stackdriver Monitoring.
	// Exporters use Application Default Credentials to authenticate.
	// See https://developers.google.com/identity/protocols/application-default-credentials
	// for more details.
	exporter, err := stackdriver.NewExporter(stackdriver.Options{})
	if err != nil {
		log.Fatal(err)
	}
	// Flush must be called before main() exits to ensure metrics are recorded.
	defer exporter.Flush()

	if err := exporter.StartMetricsExporter(); err != nil {
		log.Fatalf("Error starting metric exporter: %v", err)
	}
	defer exporter.StopMetricsExporter()

	// Record 100 fake latency values between 0 and 5 seconds.
	for i := 0; i < 100; i++ {
		ms := float64(5*time.Second/time.Millisecond) * rand.Float64()
		fmt.Printf("Latency %d: %f\n", i, ms)
		stats.Record(ctx, latencyMs.M(ms))
		time.Sleep(1 * time.Second)
	}

	fmt.Println("Done recording metrics")
}

Java


import com.google.common.collect.Lists;
import io.opencensus.exporter.stats.stackdriver.StackdriverStatsExporter;
import io.opencensus.stats.Aggregation;
import io.opencensus.stats.BucketBoundaries;
import io.opencensus.stats.Measure.MeasureLong;
import io.opencensus.stats.Stats;
import io.opencensus.stats.StatsRecorder;
import io.opencensus.stats.View;
import io.opencensus.stats.View.Name;
import io.opencensus.stats.ViewManager;
import java.io.IOException;
import java.util.Collections;
import java.util.Random;
import java.util.concurrent.TimeUnit;

public class Quickstart {
  private static final int EXPORT_INTERVAL = 70;
  private static final MeasureLong LATENCY_MS =
      MeasureLong.create("task_latency", "The task latency in milliseconds", "ms");
  // Latency in buckets:
  // [>=0ms, >=100ms, >=200ms, >=400ms, >=1s, >=2s, >=4s]
  private static final BucketBoundaries LATENCY_BOUNDARIES =
      BucketBoundaries.create(Lists.newArrayList(0d, 100d, 200d, 400d, 1000d, 2000d, 4000d));
  private static final StatsRecorder STATS_RECORDER = Stats.getStatsRecorder();

  public static void main(String[] args) throws IOException, InterruptedException {
    // Register the view. It is imperative that this step exists,
    // otherwise recorded metrics will be dropped and never exported.
    View view =
        View.create(
            Name.create("task_latency_distribution"),
            "The distribution of the task latencies.",
            LATENCY_MS,
            Aggregation.Distribution.create(LATENCY_BOUNDARIES),
            Collections.emptyList());

    ViewManager viewManager = Stats.getViewManager();
    viewManager.registerView(view);

    // Enable OpenCensus exporters to export metrics to Stackdriver Monitoring.
    // Exporters use Application Default Credentials to authenticate.
    // See https://developers.google.com/identity/protocols/application-default-credentials
    // for more details.
    StackdriverStatsExporter.createAndRegister();

    // Record 100 fake latency values between 0 and 5 seconds.
    Random rand = new Random();
    for (int i = 0; i < 100; i++) {
      long ms = (long) (TimeUnit.MILLISECONDS.convert(5, TimeUnit.SECONDS) * rand.nextDouble());
      System.out.println(String.format("Latency %d: %d", i, ms));
      STATS_RECORDER.newMeasureMap().put(LATENCY_MS, ms).record();
    }

    // The default export interval is 60 seconds. The thread with the StackdriverStatsExporter must
    // live for at least the interval past any metrics that must be collected, or some risk being
    // lost if they are recorded after the last export.

    System.out.println(
        String.format(
            "Sleeping %d seconds before shutdown to ensure all records are flushed.",
            EXPORT_INTERVAL));
    Thread.sleep(TimeUnit.MILLISECONDS.convert(EXPORT_INTERVAL, TimeUnit.SECONDS));
  }
}

Node.js

'use strict';

const {globalStats, MeasureUnit, AggregationType} = require('@opencensus/core');
const {StackdriverStatsExporter} = require('@opencensus/exporter-stackdriver');

const EXPORT_INTERVAL = process.env.EXPORT_INTERVAL || 60;
const LATENCY_MS = globalStats.createMeasureInt64(
  'task_latency',
  MeasureUnit.MS,
  'The task latency in milliseconds'
);

// Register the view. It is imperative that this step exists,
// otherwise recorded metrics will be dropped and never exported.
const view = globalStats.createView(
  'task_latency_distribution',
  LATENCY_MS,
  AggregationType.DISTRIBUTION,
  [],
  'The distribution of the task latencies.',
  // Latency in buckets:
  // [>=0ms, >=100ms, >=200ms, >=400ms, >=1s, >=2s, >=4s]
  [0, 100, 200, 400, 1000, 2000, 4000]
);

// Then finally register the views
globalStats.registerView(view);

// Enable OpenCensus exporters to export metrics to Stackdriver Monitoring.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
// Expects ADCs to be provided through the environment as ${GOOGLE_APPLICATION_CREDENTIALS}
// A Stackdriver workspace is required and provided through the environment as ${GOOGLE_PROJECT_ID}
const projectId = process.env.GOOGLE_PROJECT_ID;

// GOOGLE_APPLICATION_CREDENTIALS are expected by a dependency of this code
// Not this code itself. Checking for existence here but not retaining (as not needed)
if (!projectId || !process.env.GOOGLE_APPLICATION_CREDENTIALS) {
  throw Error('Unable to proceed without a Project ID');
}

// The minimum reporting period for Stackdriver is 1 minute.
const exporter = new StackdriverStatsExporter({
  projectId: projectId,
  period: EXPORT_INTERVAL * 1000,
});

// Pass the created exporter to Stats
globalStats.registerExporter(exporter);

// Record 100 fake latency values between 0 and 5 seconds.
for (let i = 0; i < 100; i++) {
  const ms = Math.floor(Math.random() * 5);
  console.log(`Latency ${i}: ${ms}`);
  globalStats.record([
    {
      measure: LATENCY_MS,
      value: ms,
    },
  ]);
}

/**
 * The default export interval is 60 seconds. The thread with the
 * StackdriverStatsExporter must live for at least the interval past any
 * metrics that must be collected, or some risk being lost if they are recorded
 * after the last export.
 */
setTimeout(() => {
  console.log('Done recording metrics.');
  globalStats.unregisterExporter(exporter);
}, EXPORT_INTERVAL * 1000);

Python


from random import random
import time

from opencensus.ext.stackdriver import stats_exporter
from opencensus.stats import aggregation
from opencensus.stats import measure
from opencensus.stats import stats
from opencensus.stats import view

# A measure that represents task latency in ms.
LATENCY_MS = measure.MeasureFloat(
    "task_latency",
    "The task latency in milliseconds",
    "ms")

# A view of the task latency measure that aggregates measurements according to
# a histogram with predefined bucket boundaries. This aggregate is periodically
# exported to Stackdriver Monitoring.
LATENCY_VIEW = view.View(
    "task_latency_distribution",
    "The distribution of the task latencies",
    [],
    LATENCY_MS,
    # Latency in buckets: [>=0ms, >=100ms, >=200ms, >=400ms, >=1s, >=2s, >=4s]
    aggregation.DistributionAggregation(
        [100.0, 200.0, 400.0, 1000.0, 2000.0, 4000.0]))

def main():
    # Register the view. Measurements are only aggregated and exported if
    # they're associated with a registered view.
    stats.stats.view_manager.register_view(LATENCY_VIEW)

    # Create the Stackdriver stats exporter and start exporting metrics in the
    # background, once every 60 seconds by default.
    exporter = stats_exporter.new_stats_exporter()
    print('Exporting stats to project "{}"'
          .format(exporter.options.project_id))

    # Register exporter to the view manager.
    stats.stats.view_manager.register_exporter(exporter)

    # Record 100 fake latency values between 0 and 5 seconds.
    for num in range(100):
        ms = random() * 5 * 1000

        mmap = stats.stats.stats_recorder.new_measurement_map()
        mmap.measure_float_put(LATENCY_MS, ms)
        mmap.record()

        print("Fake latency recorded ({}: {})".format(num, ms))

    # Keep the thread alive long enough for the exporter to export at least
    # once.
    time.sleep(65)

if __name__ == '__main__':
    main()
Cuando estos datos de métricas se exportan a Cloud Monitoring, puedes usarlos como cualquier otro dato.

El programa crea una vista de OpenCensus que se llama task_latency_distribution. Esta string se vuelve 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.

Si ejecutaste el programa de muestra, puedes usar el Explorador de métricas para ver tus datos:
  1. En Google Cloud Console, ve a la página Explorador de métricas en Monitoring.

    2. Ir al Explorador de métricas

  2. En la barra de herramientas, selecciona la pestaña Explorador.
  3. Selecciona la pestaña Configuración.
  4. 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:
    1. En el menú Recursos activos, selecciona tu recurso supervisado. Si ejecutas el programa en un entorno local, selecciona Global.
    2. En el menú Categorías de métricas activas, selecciona Personalizado.
    3. En el menú Métricas activas, selecciona Distribución de latencia de tareas.
    4. Haga clic en Aplicar.
  5. 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.
  6. 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 muestran las series temporales recopiladas después de ejecutar el programa en un entorno local:

Métricas de OpenCensus en Cloud Monitoring

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 métricas de OpenCensus en Cloud Monitoring

Usa métricas personalizadas, incluidas las que escribe OpenCensus, como las métricas integradas. Puedes graficarlas, establecer alertas, leerlas y supervisarlas.

En esta sección, se ilustra cómo usar el Explorador de API para leer datos de métrica. Para obtener información sobre cómo leer los 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 integradas y personalizadas.
  • 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 usas herramientas de creación 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 métrica mediante la API de Monitoring de forma directa, debes conocer los nombres de Cloud Monitoring a los que se exportaron las métricas de OpenCensus. Para determinar estos nombres, recupera los descriptores de métricas que crea el exportador y, luego, observa el campo type. Para obtener detalles sobre los descriptores de métricas, consulta MetricDescriptor.

A fin de ver los descriptores de métricas creados para las métricas exportadas, haz lo siguiente:

  1. Ve a la página de referencia de metricDescriptors.list.

  2. En el widget Prueba esta API de la página de referencia, completa los siguientes campos:

    1. 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 ID a-gcp-project.

    2. Ingresa un filtro en el campo filter. Hay muchos descriptores de métricas en un proyecto. El filtrado te permite eliminar los descriptores que no son de interés.

      Por ejemplo, debido a que el nombre de la vista de OpenCensus se vuelve 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. Consulta TimeSeries para obtener más detalles.

    3. 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 manualmente los datos asociados con el tipo de métrica. El valor del campo type también se muestra en Google Cloud Console cuando trazas la métrica.

Recuperar métricas de datos

Para recuperar manualmente datos de series temporales de un tipo de métrica, haz lo siguiente:

  1. Ve a la página de referencia de timeSeries.list.

  2. En el widget Prueba esta API de la página de referencia, completa los siguientes campos:

    1. Ingresa el nombre de tu proyecto en el campo name. Usa la siguiente estructura de nombre projects/PROJECT_ID.

    2. En el campo filter, ingresa el siguiente valor:

      metric.type="custom.googleapis.com/opencensus/task_latency_distribution"

    3. Ingresa los valores para los campos interval.startTime y interval.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 valor startTime sea anterior al valor endTime.

    4. Haga clic en el botón Execute.

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 la métrica que se muestran incluyen lo siguiente:

  • 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 y aws_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 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 escritas por OpenCensus.

Las construcciones que usa la API de OpenCensus difieren de las construcciones que usa Cloud Monitoring, al igual que 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”.

Para 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étricas 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 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 a TimeSeries en la API de Monitoring.

¿Qué sigue?