Como criar métricas personalizadas

As métricas personalizadas são métricas definidas pelos usuários. Nesta página, descrevemos como criar descritores de métricas para métricas personalizadas e como gravar dados de métricas personalizadas.

As métricas personalizadas usam os mesmos elementos que as métricas integradas do Cloud Monitoring usam:

  • Um conjunto de pontos de dados
  • Informações sobre tipo de métrica, que dizem o que os pontos de dados representam
  • Informações de recursos monitorados, que mostram onde os pontos de dados se originaram

As métricas personalizadas podem ser usadas da mesma forma que as métricas integradas. Ou seja, você pode criar gráficos e alertas para seus dados de métrica personalizada.

Antes de começar

Se você não estiver familiarizado com as estruturas que funcionam por todas as métricas, consulte Métricas, séries temporais e recursos.

Primeiros passos com as métricas personalizadas

Para usar uma métrica personalizada, é preciso ter um descritor de métrica para o novo tipo. O descritor de métrica define como seus dados são organizados. Antes de começar a gravar dados de métricas personalizadas, determine como você quer usar os dados coletados e verifique se a organização oferece suporte a esses objetivos.

Como criar um descritor de métrica

O Cloud Monitoring pode criar o descritor de métrica para você automaticamente, ou é possível usar o método metricDescriptors.create na API Monitoring para criá-lo. Não é possível manipular descritores de métrica usando o Console do Google Cloud para o Monitoring.

Para que o Cloud Monitoring crie o descritor de métrica para você, você simplesmente escreve os dados da série temporal da métrica, e o Cloud Monitoring cria um descritor com base nos dados que você está escrevendo. Para saber mais, consulte Criação automática de descritores de métricas. Há limites para a criação automática. Por isso, é útil saber quais informações são incluídas na definição de uma métrica. Depois de criar um novo descritor de métrica personalizado (criado por você ou pelo Monitoring), será possível usá-lo com métodos da API do descritor de métrica e métodos da API da série temporal.

Independentemente de você criar explicitamente o descritor de métrica ou permitir que o Monitoring o crie para você com base nos seus dados, ainda será necessário garantir que a organização dos dados corresponda à consulta.

Como organizar seus dados

Suponha que você tenha um programa executado em uma única máquina, e este programa chame programas auxiliares A e B. Você quer contar com que frequência os programas A e B são chamados. Você também quer saber quando o programa A é chamado mais de 10 vezes por minuto e quando o programa B é chamado mais de 5 vezes por minuto.

Para simplificar a discussão, suponha que você tenha um único projeto do Google Cloud e planeje usar o recurso monitorado global. Para mais informações sobre essa escolha, consulte Recursos monitorados para métricas personalizadas.

Considere as seguintes abordagens:

  • Você usa duas métricas personalizadas: Metric-type-A conta chamadas para o programa A, e Metric-type-B conta para chamadas para o programa B. Nesse caso, Metric-type-A contém uma série temporal e Metric-type-B contém uma série temporal.

    Com esse modelo de dados, você pode criar uma única política de alerta com duas condições ou duas políticas de alerta, cada uma com uma condição. Uma política de alertas é compatível com várias condições, mas tem uma única configuração para os canais de notificação.

    Esse modelo pode ser apropriado quando você não tem interesse em semelhanças nos dados entre as atividades que estão sendo monitoradas. Neste exemplo, as atividades são a taxa de chamadas para programas A e B.

  • Use uma única métrica personalizada e um rótulo para armazenar um identificador de programa. Por exemplo, o rótulo pode armazenar o valor A ou B. Como o Monitoring cria uma série temporal para cada combinação exclusiva de rótulos, há duas séries temporais para esse único tipo de métrica.

    Assim como no modelo anterior, você pode criar uma única política de alertas ou duas políticas de alertas. No entanto, as condições da política de alertas são mais complicadas. Para criar uma condição que gere um incidente se a taxa de chamadas do programa A exceder um limite, a condição precisará incluir um filtro que inclua pontos de dados cujo valor de rótulo seja A e exclua todos os outros pontos de dados.

    Uma vantagem desse modelo é que é simples calcular proporções. Por exemplo, você pode determinar quanto do total é devido a chamadas para A.

  • Use uma única métrica personalizada para contar o número de chamadas, mas não use um rótulo para registrar qual programa foi chamado. Nesse modelo, há uma única série temporal que combina os dados dos dois programas. No entanto, não é possível criar uma política de alertas que atenda aos seus objetivos porque os dados de dois programas não podem ser separados.

Como nomear métricas personalizadas

Ao criar uma métrica personalizada, você define um identificador de string que representa o tipo de métrica. Essa string precisa ser única entre as métricas personalizadas no projeto do Google Cloud e usar um prefixo que marque a métrica como uma métrica definida pelo usuário. Para o Monitoring, os prefixos permitidos são custom.googleapis.com/ e external.googleapis.com/prometheus. O prefixo é seguido por um nome que descreve o que você está coletando. Para detalhes sobre a maneira recomendada de nomear uma métrica personalizada, consulte Convenções de nomenclatura. Veja abaixo alguns exemplos dos dois tipos de identificadores de tipos de métricas:

custom.googleapis.com/cpu_utilization
custom.googleapis.com/instance/cpu/utilization

Todos os tipos de métrica têm identificadores exclusivos globalmente chamados nomes de recursos. A estrutura de um nome de recurso para um tipo de métrica é:

projects/[PROJECT_ID]/metricDescriptors/[METRIC_TYPE]

em que METRIC_TYPE é o identificador de string do tipo de métrica. Se os exemplos de métricas personalizadas anteriores tiverem sido criados no projeto my-project-id, os nomes dos recursos dessas métricas serão:

projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization

Nome ou tipo? No descritor de métrica, o campo name armazena o nome do recurso do tipo de métrica e o campo type armazena a string METRIC_TYPE.

Como escolher um tipo de recurso monitorado

Ao gravar dados em uma série temporal, você precisa indicar qual é a origem dos dados. Para isso, escolha um tipo de recurso monitorado que representa o local de onde vêm os seus dados e use-o para descrever a origem específica. O recurso monitorado não faz parte do tipo de métrica. Em vez disso, a série temporal em que você grava os dados inclui referências ao tipo de métrica, que descreve os dados e uma referência ao recurso monitorado, que indica onde os dados foram originados.

Avalie o recurso monitorado antes de criar o descritor de métrica. O tipo de recurso monitorado que você usa afeta os rótulos que você precisa incluir no descritor de métrica. Por exemplo, se você usar um recurso monitorado da instância de VM com seus dados, não precisará de um rótulo de métrica para especificar a instância. Para mais informações, consulte Recursos monitorados para métricas personalizadas.

Cada ponto de dados da sua métrica precisa estar associado a um objeto de recurso monitorado. Os pontos de diferentes objetos de recursos monitorados são mantidos em séries temporais distintas.

Recursos monitorados para métricas personalizadas

Use somente os tipos de recursos monitorados abaixo nas métricas personalizadas:

É uma prática comum usar os objetos de recursos monitorados que representam os recursos físicos em que o código do aplicativo está sendo executado. Essa abordagem tem várias vantagens:

  • Você consegue melhor desempenho em comparação com o uso de um único tipo de recurso.
  • Você evita dados fora de ordem causados pela gravação de vários processos na mesma série temporal.
  • É possível agrupar os dados da métrica personalizada com os de outras dos mesmos recursos.

global x recursos genéricos

Os tipos de recurso generic_task e generic_node são úteis em situações em que nenhum outro tipo mais específico é apropriado. O tipo generic_task é útil para definir recursos semelhantes a tarefas, como aplicativos. O tipo generic_node é útil para definir recursos semelhantes a nós, como máquinas virtuais. Os dois tipos generic_* têm vários rótulos comuns que podem ser usados para definir objetos de recursos exclusivos, facilitando o uso deles em filtros de métricas para agregações e reduções.

Por outro lado, o tipo de recurso global só tem os rótulos project_id e location. Se você tiver muitas fontes de métricas dentro de um projeto, usar o mesmo objeto de recurso global pode causar conflitos e sobreposições dos dados da métrica.

Como criar descritores de métrica

Os dados coletados para uma métrica personalizada precisam estar associados a um objeto MetricDescriptor que especifica várias informações sobre a métrica.

Você mesmo pode criar o descritor de métrica ou deixar o Monitoring para você.

É possível alterar um descritor existente de algumas formas. Consulte Como modificar descritores de métrica para mais informações.

Criação automática de descritores de métrica

Se você gravar dados de métrica quando um descritor de métrica para essa métrica personalizada ainda não existir, um descritor de métrica será criado automaticamente. No entanto, talvez ele não seja exatamente o que você quer. A criação automática de descritores de métrica inclui algumas suposições e padrões.

Especificamente, durante uma chamada para timeSeries.create, se um objeto TimeSeries incluir um objeto Metric que especifique um nome do tipo de métrica que não existe, o Cloud Monitoring cria um novo MetricDescriptor com os seguintes campos:

  • type: o tipo é copiado do campo type no objeto Metric.
  • name: o nome é criado a partir do ID do projeto na chamada do método e do valor de type no objeto Metric.
  • labels: os rótulos são aqueles que aparecem no objeto Metric. Cada descritor de rótulo no novo descritor de métrica tem os campos abaixo:
    • key: a chave do rótulo no objeto Metric.
    • valueType: STRING
    • description: não definido
  • metricKind: o tipo de métrica padrão é GAUGE, mas se você especificar o parâmetro metricKind do objeto TimeSeries, a nova métrica terá esse tipo. Só é possível especificar os tipos GAUGE e CUMULATIVE.
  • valueType: o tipo de valor é retirado do valor digitado de Point que está sendo escrito. que precisam ser BOOL, INT64, DOUBLE ou DISTRIBUTION. Se você especificar um tipo de valor no campo valueType de TimeSeries, esse tipo precisará corresponder ao tipo de Point.
  • unit: não definido
  • description: "Auto created custom metric.".
  • displayName: não definido

Em uma única chamada timeSeries.create, é possível incluir vários objetos TimeSeries que se referem ao mesmo tipo de métrica inexistente. Nesse caso, os campos do novo tipo são definidos da mesma maneira, exceto pelo fato de que os rótulos no novo descritor de métrica consistem na união de todos os rótulos nos objetos Metric em todo o tempo série nesta chamada para create.

Próxima etapa: veja Como gravar dados de métrica.

Como criar descritores de métrica manualmente

Nesta seção, você verá como criar o descritor de métrica para sua métrica personalizada.

Antes de começar

Siga estas etapas:

  • Escolha um nome ou identificador de métrica para a métrica personalizada.

  • Escolha um nome de exibição e uma descrição para a métrica. O nome de exibição é usado no Console do Google Cloud.

  • Escolha um projeto ou projetos em que você defina a métrica personalizada e grave os dados da série temporal. Se você precisar da mesma métrica em vários projetos, faça definições idênticas dela em cada projeto.

    Para gravar métricas personalizadas de recursos gerenciados por uma conta da AWS, crie o descritor de métrica no projeto de conector da AWS dessa conta.

  • Determine o tipo de métrica e de valor e, se quiser, as unidades. Nem todos os tipos de valores e métricas são compatíveis com métricas personalizadas. Para mais informações sobre esses campos, consulte Tipos de valores e métricas.

  • Escolha os rótulos da métrica: nomes, tipos de valor e descrições.

Navegar pelas métricas integradas e analisar os dados da série temporal delas ajudará você a fazer essas escolhas.

Como criar um descritor de métrica

Para criar o descritor para a métrica personalizada, chame o método metricDescriptors.create, passando um objeto MetricDescriptor.

Geralmente, é um erro chamar metricDescriptors.create usando o mesmo nome de tipo que um descritor de métrica personalizada atual. No entanto, se todos os campos do novo objeto MetricDescriptor corresponderem exatamente aos campos do descritor existente, ele não será um erro, mas não terá efeito.

No exemplo a seguir, você cria uma métrica personalizada "gauge".

Protocolo

Para criar um descritor de métrica, use o método metricDescriptors.create. É possível executá-lo por meio do widget da API Explorer na página de referência do método. Consulte a API Explorer para mais informações.

Veja a seguir os parâmetros de exemplo para metricDescriptors.create:

  • nome (URL): projects/[PROJECT_ID]
  • Corpo da solicitação: forneça um objeto MetricDescriptor como o seguinte:

    {
      "name": "",
      "description": "Daily sales records from all branch stores.",
      "displayName": "Sales",
      "type": "custom.googleapis.com/stores/sales",
      "metricKind": "CUMULATIVE",
      "valueType": "DOUBLE",
      "unit": "{USD}",
      "labels": [
        {
          "key": "store_id",
          "valueType": "STRING",
          "description": "The ID of the store."
        },
      ],
    }
    

Insira esses valores nos campos no widget, usando o ID do projeto no lugar de [PROJECT_ID]:

Experimente esta caixa de diálogo da API preenchida com o corpo da solicitação para criar um descritor de métrica.

Clique em Executar para executar o método.

Faça o teste!

Ao criar uma nova métrica personalizada, o campo name em MetricDescriptor é ignorado e pode ser omitido. O método create retorna o novo descritor de métrica com o campo name preenchido, que neste exemplo seria:

"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"

Se, por exemplo, você quiser conseguir o descritor de uma métrica, use esse nome.

C#

        public static object CreateMetric(string projectId,
            string metricType = "custom.googleapis.com/stores/daily_sales")
        {
            // Create client.
            MetricServiceClient metricServiceClient = MetricServiceClient.Create();

            // Prepare custom metric descriptor.
            MetricDescriptor metricDescriptor = new MetricDescriptor();
            metricDescriptor.DisplayName = "Daily Sales";
            metricDescriptor.Description = "Daily sales records from all branch stores.";
            metricDescriptor.MetricKind = MetricKind.Gauge;
            metricDescriptor.ValueType = MetricDescriptor.Types.ValueType.Double;
            metricDescriptor.Type = metricType;
            metricDescriptor.Unit = "{USD}";
            LabelDescriptor labels = new LabelDescriptor();
            labels.Key = "store_id";
            labels.ValueType = LabelDescriptor.Types.ValueType.String;
            labels.Description = "The ID of the store.";
            metricDescriptor.Labels.Add(labels);
            CreateMetricDescriptorRequest request = new CreateMetricDescriptorRequest
            {
                ProjectName = new ProjectName(projectId),
            };
            request.MetricDescriptor = metricDescriptor;
            // Make the request.
            MetricDescriptor response = metricServiceClient.CreateMetricDescriptor(request);
            Console.WriteLine("Done creating metric descriptor:");
            Console.WriteLine(JObject.Parse($"{response}").ToString());
            return 0;
        }

Go


import (
	"context"
	"fmt"
	"io"

	monitoring "cloud.google.com/go/monitoring/apiv3"
	"google.golang.org/genproto/googleapis/api/label"
	"google.golang.org/genproto/googleapis/api/metric"
	metricpb "google.golang.org/genproto/googleapis/api/metric"
	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
)

// createCustomMetric creates a custom metric specified by the metric type.
func createCustomMetric(w io.Writer, projectID, metricType string) (*metricpb.MetricDescriptor, error) {
	ctx := context.Background()
	c, err := monitoring.NewMetricClient(ctx)
	if err != nil {
		return nil, err
	}
	defer c.Close()
	md := &metric.MetricDescriptor{
		Name: "Custom Metric",
		Type: metricType,
		Labels: []*label.LabelDescriptor{{
			Key:         "environment",
			ValueType:   label.LabelDescriptor_STRING,
			Description: "An arbitrary measurement",
		}},
		MetricKind:  metric.MetricDescriptor_GAUGE,
		ValueType:   metric.MetricDescriptor_INT64,
		Unit:        "s",
		Description: "An arbitrary measurement",
		DisplayName: "Custom Metric",
	}
	req := &monitoringpb.CreateMetricDescriptorRequest{
		Name:             "projects/" + projectID,
		MetricDescriptor: md,
	}
	m, err := c.CreateMetricDescriptor(ctx, req)
	if err != nil {
		return nil, fmt.Errorf("could not create custom metric: %v", err)
	}

	fmt.Fprintf(w, "Created %s\n", m.GetName())
	return m, nil
}

Java

// Your Google Cloud Platform project ID
String projectId = System.getProperty("projectId");
String metricType = CUSTOM_METRIC_DOMAIN + "/" + type;

final MetricServiceClient client = MetricServiceClient.create();
ProjectName name = ProjectName.of(projectId);

MetricDescriptor descriptor =
    MetricDescriptor.newBuilder()
        .setType(metricType)
        .addLabels(
            LabelDescriptor.newBuilder()
                .setKey("store_id")
                .setValueType(LabelDescriptor.ValueType.STRING))
        .setDescription("This is a simple example of a custom metric.")
        .setMetricKind(MetricDescriptor.MetricKind.GAUGE)
        .setValueType(MetricDescriptor.ValueType.DOUBLE)
        .build();

CreateMetricDescriptorRequest request =
    CreateMetricDescriptorRequest.newBuilder()
        .setName(name.toString())
        .setMetricDescriptor(descriptor)
        .build();

client.createMetricDescriptor(request);

Node.js

// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates a client
const client = new monitoring.MetricServiceClient();

/**
 * TODO(developer): Uncomment and edit the following lines of code.
 */
// const projectId = 'YOUR_PROJECT_ID';

const request = {
  name: client.projectPath(projectId),
  metricDescriptor: {
    description: 'Daily sales records from all branch stores.',
    displayName: 'Daily Sales',
    type: 'custom.googleapis.com/stores/daily_sales',
    metricKind: 'GAUGE',
    valueType: 'DOUBLE',
    unit: '{USD}',
    labels: [
      {
        key: 'store_id',
        valueType: 'STRING',
        description: 'The ID of the store.',
      },
    ],
  },
};

// Creates a custom metric descriptor
const [descriptor] = await client.createMetricDescriptor(request);
console.log('Created custom Metric:\n');
console.log(`Name: ${descriptor.displayName}`);
console.log(`Description: ${descriptor.description}`);
console.log(`Type: ${descriptor.type}`);
console.log(`Kind: ${descriptor.metricKind}`);
console.log(`Value Type: ${descriptor.valueType}`);
console.log(`Unit: ${descriptor.unit}`);
console.log('Labels:');
descriptor.labels.forEach(label => {
  console.log(`  ${label.key} (${label.valueType}) - ${label.description}`);
});

PHP

use Google\Cloud\Monitoring\V3\MetricServiceClient;
use Google\Api\LabelDescriptor;
use Google\Api\LabelDescriptor_ValueType;
use Google\Api\MetricDescriptor;
use Google\Api\MetricDescriptor_MetricKind;
use Google\Api\MetricDescriptor_ValueType;

/**
 * Create a new metric in Stackdriver Monitoring.
 * Example:
 * ```
 * create_metric($projectId);
 * ```
 *
 * @param string $projectId Your project ID
 */
function create_metric($projectId)
{
    $metrics = new MetricServiceClient([
        'projectId' => $projectId,
    ]);

    $projectName = $metrics->projectName($projectId);

    $descriptor = new MetricDescriptor();
    $descriptor->setDescription('Daily sales records from all branch stores.');
    $descriptor->setDisplayName('Daily Sales');
    $descriptor->setType('custom.googleapis.com/stores/daily_sales');
    $descriptor->setMetricKind(MetricDescriptor_MetricKind::GAUGE);
    $descriptor->setValueType(MetricDescriptor_ValueType::DOUBLE);
    $descriptor->setUnit('{USD}');
    $label = new LabelDescriptor();
    $label->setKey('store_id');
    $label->setValueType(LabelDescriptor_ValueType::STRING);
    $label->setDescription('The ID of the store.');
    $labels = [$label];
    $descriptor->setLabels($labels);

    $descriptor = $metrics->createMetricDescriptor($projectName, $descriptor);
    printf('Created a metric: ' . $descriptor->getName() . PHP_EOL);
}

Python

client = monitoring_v3.MetricServiceClient()
project_name = f"projects/{project_id}"
descriptor = ga_metric.MetricDescriptor()
descriptor.type = "custom.googleapis.com/my_metric" + str(uuid.uuid4())
descriptor.metric_kind = ga_metric.MetricDescriptor.MetricKind.GAUGE
descriptor.value_type = ga_metric.MetricDescriptor.ValueType.DOUBLE
descriptor.description = "This is a simple example of a custom metric."

labels = ga_label.LabelDescriptor()
labels.key = "TestLabel"
labels.value_type = ga_label.LabelDescriptor.ValueType.STRING
labels.description = "This is a test label"
descriptor.labels.append(labels)

descriptor = client.create_metric_descriptor(
    name=project_name, metric_descriptor=descriptor
)
print("Created {}.".format(descriptor.name))

Ruby

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
project_name = client.project_path project: project_id

descriptor = Google::Api::MetricDescriptor.new(
  type:        metric_type,
  metric_kind: Google::Api::MetricDescriptor::MetricKind::GAUGE,
  value_type:  Google::Api::MetricDescriptor::ValueType::DOUBLE,
  description: "This is a simple example of a custom metric."
)

result = client.create_metric_descriptor name:              project_name,
                                         metric_descriptor: descriptor
p "Created #{result.name}"
p result

Consulte Solução de problemas de chamadas da API se tiver dificuldade.

Próxima etapa: veja Como gravar dados de métrica.

Como excluir métricas

Para excluir uma métrica personalizada, exclua o respectivo descritor de métrica. Não é possível excluir os dados de série temporal armazenados no seu projeto do Google Cloud; No entanto, a exclusão do descritor de métrica torna os dados inacessíveis. Os dados vão expirar e serão excluídos de acordo com a política de retenção de dados.

Não é possível excluir o descritor de métrica para uma métrica integrada.

Para excluir seu descritor de métrica personalizada, chame o método metricDescriptors.delete.

Protocolo

Para excluir um descritor de métrica, use o método metricDescriptors.delete. É possível executá-lo por meio do widget da API Explorer na página de referência do método. Consulte a API Explorer para mais informações.

Para excluir a métrica personalizada stores/daily_sales criada em Como criar descritores de métrica manualmente:

  1. Acesse a página de referência de metricDescriptors.delete:
  2. Forneça o nome do descritor de métrica ao widget da API Explorer:

    nome: projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales

  3. Clique no botão Executar.

Faça o teste!

C#

public static object DeleteMetric(string projectId, string metricType)
{
    // Create client.
    MetricServiceClient metricServiceClient = MetricServiceClient.Create();
    // Initialize request argument(s).
    MetricDescriptorName name = new MetricDescriptorName(projectId, metricType);
    // Make the request.
    metricServiceClient.DeleteMetricDescriptor(name);
    Console.WriteLine($"Done deleting metric descriptor: {name}");
    return 0;
}

Go


import (
	"context"
	"fmt"
	"io"

	monitoring "cloud.google.com/go/monitoring/apiv3"
	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
)

// deleteMetric deletes the given metric. name should be of the form
// "projects/PROJECT_ID/metricDescriptors/METRIC_TYPE".
func deleteMetric(w io.Writer, name string) error {
	ctx := context.Background()
	c, err := monitoring.NewMetricClient(ctx)
	if err != nil {
		return err
	}
	defer c.Close()
	req := &monitoringpb.DeleteMetricDescriptorRequest{
		Name: name,
	}

	if err := c.DeleteMetricDescriptor(ctx, req); err != nil {
		return fmt.Errorf("could not delete metric: %v", err)
	}
	fmt.Fprintf(w, "Deleted metric: %q\n", name)
	return nil
}

Java

String projectId = System.getProperty("projectId");
final MetricServiceClient client = MetricServiceClient.create();
MetricDescriptorName metricName = MetricDescriptorName.of(projectId, name);
client.deleteMetricDescriptor(metricName);
System.out.println("Deleted descriptor " + name);

Node.js

// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates a client
const client = new monitoring.MetricServiceClient();

/**
 * TODO(developer): Uncomment and edit the following lines of code.
 */
// const projectId = 'YOUR_PROJECT_ID';
// const metricId = 'custom.googleapis.com/stores/daily_sales';

const request = {
  name: client.projectMetricDescriptorPath(projectId, metricId),
};

// Deletes a metric descriptor
const [result] = await client.deleteMetricDescriptor(request);
console.log(`Deleted ${metricId}`, result);

PHP

use Google\Cloud\Monitoring\V3\MetricServiceClient;

/**
 * Example:
 * ```
 * delete_metric($projectId, $databaseId);
 * ```
 *
 * @param string $projectId Your project ID
 * @param string $metricId  The ID of the Metric Descriptor to delete
 */
function delete_metric($projectId, $metricId)
{
    $metrics = new MetricServiceClient([
        'projectId' => $projectId,
    ]);

    $metricPath = $metrics->metricDescriptorName($projectId, $metricId);
    $ret = $metrics->deleteMetricDescriptor($metricPath);

    printf('Deleted a metric: ' . $metricPath . PHP_EOL);
}

Python

client = monitoring_v3.MetricServiceClient()
client.delete_metric_descriptor(name=descriptor_name)
print("Deleted metric descriptor {}.".format(descriptor_name))

Ruby

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
metric_name = client.metric_descriptor_path project:           project_id,
                                            metric_descriptor: metric_type

client.delete_metric_descriptor name: metric_name
p "Deleted metric descriptor #{metric_name}."

Consulte Solução de problemas de chamadas da API se tiver dificuldade.

Como gravar dados de métricas

É possível gravar dados somente em tipos de métricas para métricas personalizadas. Para gravar seus dados, use o método timeSeries.create. Se a série temporal já existir, esse método vai acrescentar um novo ponto de dados à série temporal existente. Se a série temporal não existir, esse método a vai criar e adicionar os dados.

Você escreve pontos de dados passando uma lista de objetos TimeSeries para timeSeries.create. O tamanho máximo da lista é de 200, e cada objeto nela precisa especificar uma série temporal diferente:

  • Cada série temporal é identificada pelos campos metric e resource do objeto TimeSeries. Esses campos representam o tipo de métrica dos dados e o recurso monitorado a partir do qual os dados foram coletados.
  • Omita os campos metricKind e valueType. Eles são ignorados ao gravar pontos de dados.
  • Cada objeto TimeSeries pode conter apenas um único objeto Point:

    • O valor do ponto e o intervalo de tempo precisam ser consistentes com a definição do tipo de métrica. Para informações sobre intervalos de tempo de tipos diferentes de métricas, consulte TimeInterval.
    • O intervalo de tempo do ponto precisa ser posterior a qualquer ponto atual na série temporal.
    • O tempo de término do intervalo não pode ser maior que 25 horas no passado nem que cinco minutos no futuro.
  • Se você quiser gravar mais de um ponto para a mesma série temporal, use uma chamada separada para o método timeSeries.create para cada ponto. Não grave dados em uma única série temporal mais rapidamente do que um ponto a cada 10 segundos. Se você estiver adicionando pontos de dados a séries temporais diferentes, não haverá limitação de taxa.

Protocolo

Para gravar dados de métricas, use o método timeSeries.create. É possível executá-lo por meio do widget da API Explorer na página de referência do método. Consulte a API Explorer para mais informações.

Para gravar um ponto na métrica personalizada stores/daily_sales criada na seção Como criar descritores de métrica manualmente:

  1. Acesse a página de referência de timeSeries.create.
  2. Forneça os parâmetros abaixo ao widget da API Explorer.
  3. Clique em Executar.

Use os seguintes parâmetros de amostra:

  • nome: projects/[PROJECT_ID]
  • corpo da solicitação: inclua uma lista de objetos TimeSeries. A amostra a seguir tem apenas uma série temporal na lista.

    {
     "timeSeries": [
      {
       "metric": {
        "type": "custom.googleapis.com/my_metric",
        "labels": {
         "my_label": "my_value"
        }
       },
       "resource": {
        "type": "gce_instance",
        "labels": {
         "project_id": "[PROJECT_ID]",
         "instance_id": "1234567890123456789",
         "zone": "us-central1-f"
        }
       },
       "points": [
        {
         "interval": {
          "endTime": "2018-06-01T10:00:00-04:00"
         },
         "value": {
          "doubleValue": 123.45
         }
        }
       ]
      }
     ]
    }
    

Faça o teste!

C#

        public static object WriteTimeSeriesData(string projectId)
        {
            // Create client.
            MetricServiceClient metricServiceClient = MetricServiceClient.Create();
            // Initialize request argument(s).
            ProjectName name = new ProjectName(projectId);
            // Prepare a data point.
            Point dataPoint = new Point();
            TypedValue salesTotal = new TypedValue();
            salesTotal.DoubleValue = 123.45;
            dataPoint.Value = salesTotal;
            Timestamp timeStamp = new Timestamp();
            timeStamp.Seconds = (long)(DateTime.UtcNow - s_unixEpoch).TotalSeconds;
            TimeInterval interval = new TimeInterval();
            interval.EndTime = timeStamp;
            dataPoint.Interval = interval;

            // Prepare custom metric.
            Metric metric = new Metric();
            metric.Type = "custom.googleapis.com/stores/daily_sales";
            metric.Labels.Add("store_id", "Pittsburgh");

            // Prepare monitored resource.
            MonitoredResource resource = new MonitoredResource();
            resource.Type = "global";
            resource.Labels.Add("project_id", projectId);

            // Create a new time series using inputs.
            TimeSeries timeSeriesData = new TimeSeries();
            timeSeriesData.Metric = metric;
            timeSeriesData.Resource = resource;
            timeSeriesData.Points.Add(dataPoint);

            // Add newly created time series to list of time series to be written.
            IEnumerable<TimeSeries> timeSeries = new List<TimeSeries> { timeSeriesData };
            // Write time series data.
            metricServiceClient.CreateTimeSeries(name, timeSeries);
            Console.WriteLine("Done writing time series data:");
            Console.WriteLine(JObject.Parse($"{timeSeriesData}").ToString());
            return 0;
        }

Go


// writeTimeSeriesValue writes a value for the custom metric created
func writeTimeSeriesValue(projectID, metricType string) error {
	ctx := context.Background()
	c, err := monitoring.NewMetricClient(ctx)
	if err != nil {
		return err
	}
	defer c.Close()
	now := &timestamp.Timestamp{
		Seconds: time.Now().Unix(),
	}
	req := &monitoringpb.CreateTimeSeriesRequest{
		Name: "projects/" + projectID,
		TimeSeries: []*monitoringpb.TimeSeries{{
			Metric: &metricpb.Metric{
				Type: metricType,
				Labels: map[string]string{
					"environment": "STAGING",
				},
			},
			Resource: &monitoredres.MonitoredResource{
				Type: "gce_instance",
				Labels: map[string]string{
					"instance_id": "test-instance",
					"zone":        "us-central1-f",
				},
			},
			Points: []*monitoringpb.Point{{
				Interval: &monitoringpb.TimeInterval{
					StartTime: now,
					EndTime:   now,
				},
				Value: &monitoringpb.TypedValue{
					Value: &monitoringpb.TypedValue_Int64Value{
						Int64Value: rand.Int63n(10),
					},
				},
			}},
		}},
	}
	log.Printf("writeTimeseriesRequest: %+v\n", req)

	err = c.CreateTimeSeries(ctx, req)
	if err != nil {
		return fmt.Errorf("could not write time series value, %v ", err)
	}
	return nil
}

Java

String projectId = System.getProperty("projectId");
// Instantiates a client
MetricServiceClient metricServiceClient = MetricServiceClient.create();

// Prepares an individual data point
TimeInterval interval =
    TimeInterval.newBuilder()
        .setEndTime(Timestamps.fromMillis(System.currentTimeMillis()))
        .build();
TypedValue value = TypedValue.newBuilder().setDoubleValue(123.45).build();
Point point = Point.newBuilder().setInterval(interval).setValue(value).build();

List<Point> pointList = new ArrayList<>();
pointList.add(point);

ProjectName name = ProjectName.of(projectId);

// Prepares the metric descriptor
Map<String, String> metricLabels = new HashMap<>();
Metric metric =
    Metric.newBuilder()
        .setType("custom.googleapis.com/my_metric")
        .putAllLabels(metricLabels)
        .build();

// Prepares the monitored resource descriptor
Map<String, String> resourceLabels = new HashMap<>();
resourceLabels.put("instance_id", "1234567890123456789");
resourceLabels.put("zone", "us-central1-f");

MonitoredResource resource =
    MonitoredResource.newBuilder().setType("gce_instance").putAllLabels(resourceLabels).build();

// Prepares the time series request
TimeSeries timeSeries =
    TimeSeries.newBuilder()
        .setMetric(metric)
        .setResource(resource)
        .addAllPoints(pointList)
        .build();

List<TimeSeries> timeSeriesList = new ArrayList<>();
timeSeriesList.add(timeSeries);

CreateTimeSeriesRequest request =
    CreateTimeSeriesRequest.newBuilder()
        .setName(name.toString())
        .addAllTimeSeries(timeSeriesList)
        .build();

// Writes time series data
metricServiceClient.createTimeSeries(request);
System.out.println("Done writing time series value.");

Node.js

// Imports the Google Cloud client library
const monitoring = require('@google-cloud/monitoring');

// Creates a client
const client = new monitoring.MetricServiceClient();

/**
 * TODO(developer): Uncomment and edit the following lines of code.
 */
// const projectId = 'YOUR_PROJECT_ID';

const dataPoint = {
  interval: {
    endTime: {
      seconds: Date.now() / 1000,
    },
  },
  value: {
    doubleValue: 123.45,
  },
};

const timeSeriesData = {
  metric: {
    type: 'custom.googleapis.com/stores/daily_sales',
    labels: {
      store_id: 'Pittsburgh',
    },
  },
  resource: {
    type: 'global',
    labels: {
      project_id: projectId,
    },
  },
  points: [dataPoint],
};

const request = {
  name: client.projectPath(projectId),
  timeSeries: [timeSeriesData],
};

// Writes time series data
const result = await client.createTimeSeries(request);
console.log('Done writing time series data.', result);

PHP

use Google\Api\Metric;
use Google\Api\MonitoredResource;
use Google\Cloud\Monitoring\V3\MetricServiceClient;
use Google\Cloud\Monitoring\V3\Point;
use Google\Cloud\Monitoring\V3\TimeInterval;
use Google\Cloud\Monitoring\V3\TimeSeries;
use Google\Cloud\Monitoring\V3\TypedValue;
use Google\Protobuf\Timestamp;

/**
 * Example:
 * ```
 * write_timeseries($projectId);
 * ```
 *
 * @param string $projectId Your project ID
 */
function write_timeseries($projectId)
{
    $metrics = new MetricServiceClient([
        'projectId' => $projectId,
    ]);

    $projectName = $metrics->projectName($projectId);

    $endTime = new Timestamp();
    $endTime->setSeconds(time());
    $interval = new TimeInterval();
    $interval->setEndTime($endTime);

    $value = new TypedValue();
    $value->setDoubleValue(123.45);

    $point = new Point();
    $point->setValue($value);
    $point->setInterval($interval);
    $points = [$point];

    $metric = new Metric();
    $metric->setType('custom.googleapis.com/stores/daily_sales');
    $labels = ['store_id' => 'Pittsburg'];
    $metric->setLabels($labels);

    $resource = new MonitoredResource();
    $resource->setType('global');
    $labels = ['project_id' => $projectId];
    $resource->setLabels($labels);

    $timeSeries = new TimeSeries();
    $timeSeries->setMetric($metric);
    $timeSeries->setResource($resource);
    $timeSeries->setPoints($points);

    $result = $metrics->createTimeSeries(
        $projectName,
        [$timeSeries]);

    printf('Done writing time series data.' . PHP_EOL);
}

Python

client = monitoring_v3.MetricServiceClient()
project_name = f"projects/{project_id}"

series = monitoring_v3.TimeSeries()
series.metric.type = "custom.googleapis.com/my_metric" + str(uuid.uuid4())
series.resource.type = "gce_instance"
series.resource.labels["instance_id"] = "1234567890123456789"
series.resource.labels["zone"] = "us-central1-f"
now = time.time()
seconds = int(now)
nanos = int((now - seconds) * 10 ** 9)
interval = monitoring_v3.TimeInterval(
    {"end_time": {"seconds": seconds, "nanos": nanos}}
)
point = monitoring_v3.Point({"interval": interval, "value": {"double_value": 3.14}})
series.points = [point]
client.create_time_series(name=project_name, time_series=[series])

Ruby

# Your Google Cloud Platform project ID
# project_id = "YOUR_PROJECT_ID"

# Example metric type
# metric_type = "custom.googleapis.com/my_metric"

client = Google::Cloud::Monitoring.metric_service
project_name = client.project_path project: project_id

series = Google::Cloud::Monitoring::V3::TimeSeries.new
series.metric = Google::Api::Metric.new type: metric_type

resource = Google::Api::MonitoredResource.new type: "global"
resource.labels["project_id"] = project_id
series.resource = resource

point = Google::Cloud::Monitoring::V3::Point.new
point.value = Google::Cloud::Monitoring::V3::TypedValue.new double_value: 3.14
now = Time.now
end_time = Google::Protobuf::Timestamp.new seconds: now.to_i, nanos: now.nsec
point.interval = Google::Cloud::Monitoring::V3::TimeInterval.new end_time: end_time
series.points << point

client.create_time_series name: project_name, time_series: [series]
p "Time series created."

Consulte Solução de problemas de chamadas da API se tiver dificuldade.

Como modificar descritores de métrica

Para adicionar rótulos a uma métrica personalizada atual, use o método timeSeries.create e inclua os novos rótulos com os dados de série temporal. Se os rótulos que você tentar gravar forem válidos e não fizerem com que o número de rótulos no descritor de métrica exceda o limite de 10, os rótulos serão adicionados. Depois, os dados da série temporal são gravados como se o rótulo estivesse lá desde o início.

Se você quer fazer mais do que adicionar novos rótulos, exclua e recrie o descritor de métrica. Nesse caso, você perde todos os dados da série temporal coletados anteriormente para o descritor de métrica antigo. Consulte Como excluir métricas para ver mais informações.

Não é possível renomear uma métrica.

A seguir