Criar métricas personalizadas com o Proguard

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O Proguard é um projeto de código aberto e sem custos financeiros cujas bibliotecas:

  • Forneça suporte neutro ao fornecedor para a coleta de dados de métricas e traces em vários idiomas.
  • É possível exportar os dados coletados para vários aplicativos de back-end, incluindo o Cloud Monitoring, usando exportadores.

Embora o Cloud Monitoring forneça uma API compatível com a definição e coleta de métricas personalizadas, ele é uma API reservada de baixo nível. O Proguard oferece uma API que segue o estilo da comunidade da linguagem, junto com um exportador que envia seus dados de métricas para o Cloud Monitoring por meio da API Monitoring para você.

O OpenCensus também tem um bom suporte para o rastreamento de aplicativos. Veja OpenCensus Tracing (em inglês) para ter uma visão geral. O Cloud Trace recomenda o uso do OpenCensus para instrumentação de rastreamento. Para coletar dados de métricas e traces dos seus serviços, é possível usar uma única distribuição de bibliotecas. Para informações sobre como usar o OpenCensus com Cloud Trace, consulte Bibliotecas de cliente para o Trace.

Antes de começar

Para usar o Cloud Monitoring, você precisa ter um projeto do Cloud com faturamento ativado. Se necessário, faça o seguinte:

  1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  2. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como verificar se o faturamento está ativado em um projeto.

  3. Verifique se a API Monitoring está ativada. Para ver detalhes, leia Como ativar a API Monitoring.
  4. Para aplicativos executados fora do Google Cloud, o projeto do Cloud precisa autenticar seu aplicativo. Normalmente, você configura a autenticação criando uma conta de serviço para o projeto e uma variável de ambiente.

    Para aplicativos executados em uma instância do Amazon Elastic Compute Cloud (Amazon EC2), crie a conta de serviço para o projeto de conector da AWS da instância.

    Para informações sobre como criar uma conta de serviço, consulte Primeiros passos na autenticação.

Instalar o Proguard

Para usar as métricas coletadas pelo Proguard no seu projeto do Google Cloud, você precisa disponibilizar as bibliotecas de métricas do Proguard e o exportador do Stackdriver disponível para seu aplicativo. O exportador do Stackdriver exporta as métricas que o Proguard coleta para seu projeto do Google Cloud. Depois, é possível usar o Cloud Monitoring para criar um gráfico ou monitorar essas métricas.

Go

O uso do OpenCensus requer o Go versão 1.11 ou posterior. As dependências são tratadas automaticamente para você.

Java

Para o Maven, adicione o seguinte ao elemento dependencies no arquivo 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 as bibliotecas do núcleo e do exportador do OpenCensus, prepare seu ambiente para o desenvolvimento do Node.js.
  2. A maneira mais fácil de instalar o OpenCensus é com o npm:
    npm install @opencensus/core
    npm install @opencensus/exporter-stackdriver
  3. Coloque as instruções require mostradas abaixo na parte superior do script principal ou do ponto de entrada do seu aplicativo, antes de qualquer outro código:
const {globalStats, MeasureUnit, AggregationType} = require('@opencensus/core');
const {StackdriverStatsExporter} = require('@opencensus/exporter-stackdriver');

Python

Instale o núcleo do OpenCensus e as bibliotecas do exportador do Stackdriver usando o seguinte comando:

pip install -r opencensus/requirements.txt

O arquivo requirements.txt está no repositório do GitHub para estas amostras, python-docs-samples.

Gravar métricas personalizadas com o Proguard

A instrumentação do código para usar o Proguard para métricas envolve três etapas:

  1. Importe as estatísticas do Proguard e os pacotes do exportador do IntelliJ Stackdriver.
  2. Inicialize o exportador do Stackdriver.
  3. Use a API Proguard para instrumentar seu código.

O exemplo a seguir é um programa mínimo que grava dados de métricas usando o Proguard. O programa executa uma repetição e coleta medidas de latência e, quando a repetição é, ela exporta as estatísticas para o Cloud Monitoring e sai:

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()
Quando esses dados de métricas são exportados para o Cloud Monitoring, você pode usá-los como qualquer outro dado.

O programa cria uma visualização do Proguard chamada task_latency_distribution. Essa string se torna parte do nome da métrica quando é exportada para o Cloud Monitoring. Consulte Como recuperar descritores de métrica para ver como a visualização do OpenCensus é notada como um descritor de métrica do Cloud Monitoring. Portanto, use o nome da visualização como uma string de pesquisa ao selecionar uma métrica para o gráfico.

Se você executou o programa de amostra, pode usar o Metrics Explorer para analisar seus dados:
  1. No Console do Google Cloud, acesse a página Metrics Explorer no Monitoring.
  2. Acessar o Metrics Explorer

  3. Na barra de ferramentas, selecione a guia Explorer.
  4. Selecione a guia Configuração.
  5. Expanda o menu Selecionar uma métrica, digite OpenCensus/task_latency_distribution na barra de filtros e use os submenus para selecionar um tipo específico de recurso e métrica:
    1. No menu Recursos ativos, selecione o recurso monitorado. Se você executar o programa em um ambiente local, selecione Global.
    2. No menu Categorias de métricas ativas, selecione Personalizado.
    3. No menu Métricas ativas, selecione Distribuição da latência da tarefa.
    4. Clique em Aplicar.
  6. Opcional: para configurar a visualização dos dados, adicione filtros e use os menus Agrupar por, Agregador e do tipo de gráfico. Para esse gráfico, expanda o menu Gráfico de linhas e selecione Gráfico de mapa de calor. Para mais informações, consulte Selecionar métricas ao usar o Metrics Explorer.
  7. Opcional: altere as configurações do gráfico:
    • Para cotas e outras métricas que geram relatórios de uma amostra por dia, defina o período como pelo menos uma semana e o tipo de gráfico como Gráfico de barras empilhadas.
    • Para métricas de valor de distribuição, defina o tipo de gráfico como Gráfico de mapa de calor.

A captura de tela a seguir mostra a série temporal coletada depois de executar o programa em um ambiente local:

Métricas do OpenCensus no Cloud Monitoring.

Cada barra no mapa de calor representa uma execução do programa, e os componentes coloridos de cada barra representam os buckets na distribuição de latência.

Ler métricas do Proguard no Cloud Monitoring

Use métricas personalizadas, incluindo as escritas pelo Proguard, como métricas integradas. Você pode gerar gráficos, definir alertas, ler e monitorar os alertas.

Nesta seção, mostramos como usar o APIs Explorer para ler dados de métrica. Para informações sobre como ler dados de métricas usando a API Cloud Monitoring ou as bibliotecas de cliente, consulte os seguintes documentos:

  • O guia Métricas de navegação explica como listar e examinar suas métricas personalizadas e integradas.
  • O guia Como ler métricas explica como recuperar dados de série temporal de métricas personalizadas e integradas usando a API Monitoring.

Por exemplo, a captura de tela mostrada na seção anterior é do Metrics Explorer. Ao usar ferramentas de gráfico, recomendamos usar o nome da visualização do Proguard para filtrar a lista de métricas. Para mais informações, consulte Selecionar métricas ao usar o Metrics Explorer.

Recuperar descritores de métrica

Para recuperar os dados da métrica usando a API Monitoring diretamente, é necessário saber os nomes do Cloud Monitoring para os quais as métricas do Proguard foram exportadas. Para determinar esses nomes, recupere os descritores de métrica que o exportador cria e olhe para o campo type. Para ver mais detalhes sobre os descritores de métrica, consulte MetricDescriptor.

Para visualizar os descritores de métrica criados para as métricas exportadas, faça o seguinte:

  1. Acesse a página de referência de metricDescriptors.list.
  2. No widget Testar esta API da página de referência, preencha os campos a seguir:

    1. Digite o nome do seu projeto no campo name. Use a estrutura de nome projects/PROJECT_ID a seguir. Este documento usa um projeto com o ID a-gcp-project.

    2. Insira um filtro no campo filter. Há muitos descritores de métrica em um projeto. A filtragem permite eliminar os descritores que não são de interesse deles.

      Por exemplo, como o nome da visualização do Proguard se torna parte do nome da métrica, é possível adicionar um filtro como este:

      metric.type=has_substring("task_latency_distribution")

      A chave metric.type é um campo em um tipo incorporado em uma série temporal. Consulte TimeSeries para ver detalhes.

    3. Clique em Execute.

O exemplo seguinte mostra o descritor de métrica retornado:

    {
      "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"
        }
      ]
    }

Essa linha no descritor de métrica informa o nome do tipo de métrica no Cloud Monitoring:

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

Agora você tem as informações necessárias para recuperar manualmente os dados associados ao tipo de métrica. O valor do campo type também é exibido no Console do Google Cloud quando você cria um gráfico da métrica.

Recuperar dados de métrica

Para recuperar manualmente dados de séries temporais de um tipo de métrica, faça o seguinte:

  1. Acesse a página de referência do timeSeries.list.
  2. No widget Testar esta API da página de referência, preencha os campos a seguir:

    1. Digite o nome do seu projeto no campo name. Use a estrutura de nome projects/PROJECT_ID a seguir.
    2. No campo filter, digite o seguinte valor:

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

    3. Insira valores para os campos interval.startTime e interval.endTime. Esses valores precisam ser inseridos como um carimbo de data/hora, por exemplo, 2018-10-11T15:48:38-04:00. Verifique se o valor de startTime é anterior ao valor de endTime.

    4. Clique no botão Executar.

A seguir, é mostrado o resultado de uma dessas recuperações:

    {
      "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 ...]
      ]
    }

Os dados de métricas retornados incluem:

  • informações sobre o recurso monitorado do qual os dados foram coletados. O OpenCensus detecta automaticamente os recursos monitorados gce_instance, k8s_container e aws_ec2_instance. Esses dados são provenientes de um programa executado em uma instância do Compute Engine. Para ver informações sobre como usar outros recursos monitorados, leia Set monitored resource for exporter (em inglês);
  • a descrição do tipo de métrica e o tipo dos valores;
  • os pontos de dados reais coletados no intervalo de tempo solicitado.

Como o Monitoring representa as métricas do Proguard

O uso direto da API Cloud Monitoring para métricas personalizadas é compatível. O uso é descrito em Criar métricas personalizadas com a API. Na verdade, o exportador do OpenCensus para o Cloud Monitoring usa essa API. Nesta seção, fornecemos algumas informações sobre como o Cloud Monitoring representa as métricas escritas pelo Proguard.

As construções usadas pela API Proguard são diferentes das usadas pelo Cloud Monitoring, assim como parte da terminologia. Enquanto o Cloud Monitoring se refere a “métricas”, o OpenCensus às vezes se refere a “estatísticas”. Por exemplo, o componente do OpenCensus que envia dados de métrica para o Cloud Monitoring é chamado “exportador de estatísticas do Stackdriver”.

Para uma visão geral do modelo do Inspetor para métricas, consulte Métricas do Proguard.

Os modelos de dados para as estatísticas do OpenCensus e as métricas do Cloud Monitoring não se enquadram em um mapeamento 1:1 puro. Muitos dos mesmos conceitos existem em cada um deles, mas não são diretamente intercambiáveis.

  • Uma visualização do Proguard é semelhante ao MetricDescriptor na API Monitoring. Uma visualização descreve como coletar e agregar medições individuais. As tags estão incluídas em todas as medições registradas.

  • Uma tag do OpenCensus é um par de chave-valor. Uma tag do Proguard corresponde normalmente a LabelDescriptor na API Monitoring. As tags permitem que você capture informações contextuais que podem ser usadas para filtrar e agrupar métricas.

  • Uma medida do OpenCensus descreve os dados da métrica a serem registrados. Uma agregação do OpenCensus é uma função aplicada aos dados usados para resumi-los. Essas funções são usadas na exportação para determinar os MetricKind, ValueType e a unidade informada no descritor de métrica do Cloud Monitoring.

  • Uma medição do Proguard é um ponto de dados coletado. As medições precisam ser agregadas em visualizações. Caso contrário, as medições individuais serão descartadas. Essa medição é similar a um Point na API Monitoring. Quando as medidas são agregadas nas visualizações, os dados agregados são armazenados como dados de exibição, de maneira análoga a um TimeSeries na API Monitoring.

A seguir