Métricas personalizadas con OpenCensus

Stackdriver Monitoring recopila automáticamente más de mil métricas incorporadas de una larga lista de recursos supervisados. No obstante, esas métricas no pueden capturar datos específicos de la aplicación o datos del sistema del lado del cliente. Esas métricas pueden proporcionarte información sobre la latencia de backend o el uso del disco, pero no pueden decirte cuántas rutinas en segundo plano generó tu aplicación.

Las métricas específicas de la aplicación son métricas que defines y recopilas para capturar información que las métricas de Stackdriver Monitoring incorporadas no pueden. Captura estas métricas mediante una API proporcionada por una biblioteca para instrumentar tu código, y luego envía las métricas a una aplicación de backend como Stackdriver Monitoring.

En Stackdriver Monitoring, las métricas específicas de la aplicación suelen denominarse "métricas personalizadas". Los términos son intercambiables. También se las llama "métricas definidas por el usuario".

En lo que respecta a Stackdriver Monitoring, las métricas personalizadas se pueden utilizar como las métricas integradas. Puedes realizar gráficos y establecer alertas con ellas, y puedes supervisarlas. La diferencia es que tú defines las métricas, escribes datos en ellas y puedes borrarlas. No se puede hacer nada de eso con las métricas integradas.

Hay muchas formas de capturar métricas personalizadas, incluido el uso de la API nativa de Stackdriver Monitoring. Stackdriver recomienda que uses OpenCensus para instrumentar tu código con el fin de recopilar métricas personalizadas.

¿Qué es OpenCensus?

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

  • Proporcionan asistencia independiente del proveedor para la recopilación de datos de métricas y de seguimiento en una variedad de lenguajes.
  • Permiten exportar los datos recopilados a una variedad de aplicaciones de backend, como Stackdriver.

Si quieres obtener la lista actual de lenguajes compatibles, consulta Lenguajes admitidos. Y si deseas obtener la lista actual de aplicaciones de backend para las que hay exportadores disponibles, consulta Exportadores.

¿Por qué elegir OpenCensus?

Si bien Stackdriver 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 mucho más idiomática, junto con un exportador que envía tus datos de métricas a Stackdriver Monitoring a través de la API de Monitoring.

Además, OpenCensus es un proyecto de código abierto. Puedes exportar los datos recopilados mediante una biblioteca independiente del proveedor en lugar de una biblioteca propietaria.

OpenCensus también tiene una buena asistencia para el seguimiento de aplicaciones; consulta Seguimiento de OpenCensus a fin de obtener una descripción general. Stackdriver recomienda usar OpenCensus para realizar el seguimiento de la instrumentación. Puedes usar una única distribución de bibliotecas para recopilar datos de métricas y de seguimiento de tus servicios. Si quieres obtener información sobre el uso de OpenCensus con Stackdriver Trace, consulta Bibliotecas cliente para Trace.

Antes de comenzar

Para usar Stackdriver Monitoring, debes tener un proyecto de GCP con la facturación habilitada. El proyecto también debe estar asociado con un lugar de trabajo de Stackdriver. Stackdriver Monitoring usa el lugar de trabajo para organizar proyectos de GCP supervisados.

Si no tienes un proyecto de GCP, haz lo siguiente:

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. Selecciona o crea un proyecto de GCP.

    Ir a la página Administrar recursos

  3. Asegúrate de tener habilitada la facturación para tu proyecto.

    Aprende a habilitar la facturación

Para asociar tu proyecto con un lugar de trabajo, consulta Lugares de trabajo.

Las métricas personalizadas son una característica con cargo de Stackdriver Monitoring y podría haber costos asociados con la transferencia de tus métricas. Para obtener más información sobre precios, consulta Precios de Stackdriver.

Instala OpenCensus

Para usar OpenCensus, debes habilitar las bibliotecas de métricas y el exportador de Stackdriver.

j# include "_shared/widgets/_sample_tab_section.html" with lang="go" project="golang-samples" file="opencensus/metrics_quickstart/main.go" region_tag=sample_id #}

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>

Cómo usar OpenCensus para métricas

La instrumentación de tu código para usar OpenCensus con tus métricas implica tres pasos generales que debes seguir:

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

Un ejemplo básico

El siguiente es un programa mínimo que ilustra estos pasos. Ejecuta un ciclo y recopila medidas de latencia, y cuando el ciclo finaliza, exporta las estadísticas a Stackdriver Monitoring y sale:

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 = 60;
  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));
  }
}

Cuando estos datos de métricas se exportan a Stackdriver, puedes usarlos como cualquier otro dato.

El programa crea una vista de OpenCensus denominada task_latency_distribution. Esta string se convierte en parte del nombre de la métrica cuando se exporta a Stackdriver Monitoring. Consulta Recupera descriptores de métricas para ver cómo se realiza la vista de OpenCensus como un descriptor de métrica de Stackdriver Monitoring.

A continuación, puedes usar el nombre de la vista como una string de búsqueda cuando seleccionas una métrica para representar. Por ejemplo, puedes escribirla en el campo Find resource type and metric (Buscar tipo de recurso y métrica) en el explorador de métricas. La siguiente captura de pantalla muestra el resultado:

Métricas de OpenCensus en Stackdriver Monitoring

Cada barra en el mapa de calor representa una ejecución del programa, y los componentes coloreados de cada barra representan depósitos en la distribución de latencia. Consulta Métricas de OpenCensus en Stackdriver para obtener más detalles sobre los datos que se encuentran detrás del gráfico.

Documentación de OpenCensus

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
Java API de Java Exportador de estadísticas Métricas

Asigna los modelos

La API de Stackdriver Monitoring nativa es compatible con las métricas personalizadas; su uso se describe en Usar métricas personalizadas. De hecho, el exportador de OpenCensus para Stackdriver usa esta API por ti.

Incluso si no necesitas conocer los detalles específicos del uso de la API de Stackdriver Monitoring, la familiaridad con sus construcciones y terminología es útil para entender cómo Stackdriver Monitoring representa las métricas. Esta sección proporciona parte de esa información.

Una vez que tus métricas se transfieren a Stackdriver, se almacenan dentro de las construcciones de Stackdriver Monitoring. Por ejemplo, puedes recuperar el descriptor de métrica (un tipo de la API de Monitoring) de una métrica personalizada. Consulta MetricDescriptor para obtener más información. Encuentras estos descriptores de métricas, por ejemplo, cuando creas gráficos para tus datos.

Terminología y conceptos

Las construcciones utilizadas por la API de OpenCensus difieren de las utilizadas por Stackdriver Monitoring; lo mismo sucede con algunos usos de la terminología. En los casos en los que Stackdriver Monitoring se refiere a “métricas”, OpenCensus a veces hace referencia a “estadísticas”. Por ejemplo, al componente de OpenCensus que envía datos de métricas en Stackdriver se lo denomina el "exportador de estadísticas para Stackdriver".

Consulta Métricas de OpenCensus a fin de obtener una descripción general del modelo de OpenCensus para métricas.

Los modelos de datos para las estadísticas de OpenCensus y Stackdriver Monitoring no se incluyen en una asignación de 1:1. Muchos de los mismos conceptos existen en cada uno, pero no son directamente intercambiables.

  • Una vista de OpenCensus generalmente es análoga al MetricDescriptor en la API de Monitoring. Una vista describe cómo recopilar y agregar mediciones individuales. Todas las mediciones registradas se desglosan por etiquetas.

  • Una etiqueta de OpenCensus es un par clave-valor. Esto generalmente corresponde al LabelDescriptor en la API de Monitoring. Las etiquetas te permiten capturar información contextual que se puede 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 aplicada a los datos utilizados para resumirla. Estos se utilizan en la exportación para determinar la MetricKind, el ValueType y la unidad informada en el descriptor de métrica de Stackdriver.

  • Una medición de OpenCensus es un dato recopilado para medición. Las mediciones deben ser agregadas en vistas. De lo contrario, las mediciones individuales se caen. Esta construcción es análoga a un Point en la API de Monitoring. Cuando las mediciones se agregan en vistas, los datos agregados se almacenan como datos de vistas, análogos a una TimeSeries en la API de Monitoring.

Métricas de OpenCensus en Stackdriver

Puedes examinar las métricas exportadas en Stackdriver Monitoring. La captura de pantalla en Un ejemplo básico se tomó del explorador de métricas. Si has ejecutado el programa de ejemplo, puedes usar el explorador de métricas para ver tus datos:

Ir a la página Explorador de métricas

Puedes proporcionar el nombre de la vista de OpenCensus cuando especificas la métrica para restringir la búsqueda. Consulta Seleccionar métricas para obtener más información.

Cómo recuperar descriptores de métricas

Puedes recuperar datos de métricas mediante la API de Monitoring de forma directa. Para recuperar datos de métricas, necesitas conocer los nombres de Stackdriver a los que se exportaron las métricas de OpenCensus.

Una forma de obtener esta información es recuperar los descriptores de métricas creados por el exportador y encontrar el valor del campo type. Este valor incorpora el nombre de la vista de OpenCensus desde la que se exportó. Para obtener detalles sobre descriptores de métricas, consulta MetricDescriptor.

Puedes ver los descriptores de métricas creados para las métricas exportadas mediante el widget (Prueba esta API) del explorador de API en la página de referencia del método metricDescriptors.list. Si quieres recuperar los descriptores de métricas para las métricas de OpenCensus mediante esta herramienta, haz lo siguiente:

  1. Ingresa el nombre de tu proyecto en el campo name: projects/[PROJECT_ID]. Este documento usa un proyecto con el ID a-gcp-project.

  2. Ingresa un filtro en el campo filter. El nombre de la vista de OpenCensus se convierte en parte del nombre de la métrica, por lo que puedes usar ese nombre para restringir la lista mediante un filtro como el siguiente:

    metric.type=has_substring("task_latency_distribution")

    Hay muchos descriptores de métricas en cualquier proyecto. El filtrado en una substring desde el nombre de la vista de OpenCensus los elimina en su mayoría.

  3. Haz clic en el botón 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 Stackdriver Monitoring:

"type": "custom.googleapis.com/opencensus/task_latency_distribution"

Con esta información, puedes recuperar manualmente los datos asociados con este tipo de métrica. Estos son también los datos que aparecen en un gráfico para esta métrica.

Cómo recuperar datos de métricas

Para recuperar manualmente datos de series temporales de un tipo de métrica, puedes utilizar la herramienta Prueba esta API en la página de referencia del método timeSeries.list:

  1. Ingresa el nombre de tu proyecto en el campo name: projects/[PROJECT_ID]
  2. Ingresa un filtro en el campo filter para el tipo de métrica deseado: metric.type="custom.googleapis.com/opencensus/task_latency_distribution"
    • La clave, metric.type, es un campo de un tipo incorporado en una serie temporal. Consulta TimeSeries para obtener más detalles.
    • El valor es el type extraído del descriptor de métrica en Recupera descriptores.
  3. Ingresa los límites temporales de la recuperación mediante la siguiente especificación de los valores para estos campos:
    • interval.endTime como una marca de tiempo, por ejemplo: 2018-10-11T15:48:38-04:00
    • interval.startTime (debe ser anterior a interval.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-21368@docbuild"
        },
        "type": "custom.googleapis.com/opencensus/task_latency_distribution"
      },
      "resource": {
        "type": "global",
        "labels": {
          "project_id": "a-gcp-project"
        }
      },
      "metricKind": "CUMULATIVE",
      "valueType": "DISTRIBUTION",
      "points": [
        {
          "interval": {
            "startTime": "2018-10-21T18:02:28.171270Z",
            "endTime": "2018-10-21T18:02:28.171366Z"
          },
          "value": {
            "distributionValue": {
              "count": "60",
              "mean": 2501.9301065269069,
              "sumOfSquaredDeviation": 116606963.10749318,
              "bucketOptions": {
                "explicitBuckets": {
                  "bounds": [
                    0,
                    100,
                    200,
                    400,
                    1000,
                    2000,
                    4000
                  ]
                }
              },
              "bucketCounts": [
                "0",
                "0",
                "2",
                "3",
                "4",
                "15",
                "25",
                "11"
              ]
            }
          }
        }
      ]
    },
    [ ... data from additional program runs deleted ...]
  ]
}

Estos datos mostrados aquí incluyen lo siguiente:

  • Información acerca del recurso supervisado sobre el cual se recopilaron los datos.
  • Descripción de la clase de métrica y el tipo de los valores.
  • Los datos reales recopilados dentro del intervalo de tiempo solicitado.
¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Esta página
Comentarios sobre la documentación
Stackdriver Monitoring
Comentarios sobre el producto
¿Necesitas ayuda? Visita nuestra página de asistencia.