Crea métricas personalizadas con OpenCensus

OpenCensus es un proyecto gratuito de código abierto cuyas bibliotecas tienen las siguientes características:

  • Proporciona compatibilidad neutral con los proveedores para la recopilación de datos de métricas y seguimientos en varios idiomas.
  • Puede exportar los datos recopilados a varias aplicaciones de backend, incluido Cloud Monitoring, mediante exportadores.

Si bien Cloud Monitoring proporciona una API que admite la definición y recopilación de métricas personalizadas, es una API propietaria de bajo nivel. OpenCensus proporciona una API mucho más idiomática, 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:

  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. Descubre cómo confirmar que tienes habilitada la facturación en un proyecto.

  3. Asegúrate de que la API de Monitoring esté habilitada. Para obtener más información, consulta Habilita la API de Monitoring.
  4. En el caso de las aplicaciones que se ejecutan fuera de Google Cloud, el proyecto de Cloud debe autenticar la aplicación. Por lo general, debes configurar la autenticación mediante la creación de una cuenta de servicio para el 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 del 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

Si deseas 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 en tu proyecto de Google Cloud. Luego, puedes usar Cloud Monitoring para graficar o supervisar esas métricas.

Comienza a usarlo

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

La instrumentación de tu código para usar OpenCensus con las métricas implica tres pasos:

  1. Importa las estadísticas de OpenCensus y los paquetes de exportación de OpenCensus para Stackdriver.
  2. Inicializa el exportador de Stackdriver.
  3. Usa la API de OpenCensus para instrumentar tu código.

En el siguiente ejemplo, se muestra un programa mínimo que escribe datos de métricas mediante OpenCensus. El programa ejecuta un bucle y recopila medidas de latencia, y cuando el bucle finaliza, exporta las estadísticas a Cloud Monitoring y sale:

Comienza a usarlo


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

Si ejecutaste el programa de ejemplo, puedes usar el Explorador de métricas para ver tus datos.

  1. En Google Cloud Console, ve a Monitoring o usa el siguiente botón:
    Ir a Monitoring
  2. En el panel de navegación de Monitoring, haz clic en  Explorador de métricas.
  3. Selecciona la pestaña Configuración y, luego, ingresa o selecciona un Tipo de recurso y una Métrica.
    • En Recurso, selecciona tu recurso supervisado. Si ejecutas el programa en un entorno local, usa el valor de Global.
    • En Métrica, selecciona o ingresa OpenCensus/task_Latency_distribution.
  4. En el tipo de gráfico, selecciona 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:

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

Debes usar métricas personalizadas, incluidas las que escribe OpenCensus, como las métricas integradas. Puedes crear gráficos, configurar alertas, leerlos y supervisarlos de otra manera.

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 los datos de métricas mediante la API de Cloud Monitoring o las bibliotecas cliente, consulta los siguientes documentos:

  • En Explora métricas, se explica cómo enumerar y examinar tus métricas integradas y personalizadas.
  • En la sección sobre cómo leer las métricas, se explica cómo recuperar datos de series temporales de métricas personalizadas y integradas mediante 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 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 las 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 directamente, 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 en 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. Un proyecto tiene muchos descriptores de métricas. Los filtros te permiten quitar los descriptores que no te interesan.

      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. 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 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 trazas la métrica.

Recuperar datos de métricas

Para recuperar datos de series temporales de un tipo de métrica de forma manual, sigue estos pasos:

  1. Ve a la página de referencia de timeSeries.list.
  2. En el widget Prueba esta API en 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 de startTime sea anterior al valor de endTime.

    4. Haz clic en el botón Ejecutar.

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 Monitoring representa 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 escritas por OpenCensus.

Las construcciones que usa la API de OpenCensus difieren de las construcciones que usa Cloud Monitoring, al igual que algún uso de 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 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. Se incluyen las etiquetas con todas las mediciones registradas.

  • Una etiqueta de OpenCensus es un par clave-valor. Por lo general, una etiqueta de OpenCensus corresponde a 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 los elementos MetricKind, ValueType y de unidades informados en el descriptor de métrica de Cloud Monitoring.

  • Una medida de OpenCensus es un dato recopilado. Las mediciones deben ser agregadas en vistas. De lo contrario, las mediciones individuales se caen. 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?