Crie métricas definidas pelo utilizador com a API

Este documento descreve como criar métricas definidas pelo utilizador e como escrever estes dados de métricas através da API Cloud Monitoring. As métricas definidas pelo utilizador usam os mesmos elementos que as métricas incorporadas do Cloud Monitoring:

• Um conjunto de pontos de dados.
• Informações do tipo métrica, que indicam o que os pontos de dados representam.
• Informações de recursos monitorizados, que indicam a origem dos pontos de dados.

As métricas definidas pelo utilizador, por vezes denominadas métricas personalizadas, podem ser usadas da mesma forma que as métricas incorporadas. Isto é, pode criar gráficos e alertas para estes dados de métricas.

As métricas baseadas em registos são uma classe de métricas definidas pelo utilizador, mas não pode criá-las através da API Cloud Monitoring. As métricas baseadas em registos derivam dados de métricas de entradas de registos, mas a API Monitoring não oferece uma forma de especificar como extrair dados de métricas de entradas de registos. Em alternativa, use o Cloud Logging para criar métricas baseadas em registos. Quando cria uma métrica baseada em registos, o Logging cria as estruturas descritas neste documento e envia os dados das métricas para o Cloud Monitoring. Para obter informações sobre como criar métricas baseadas em registos, consulte os seguintes documentos:

• Crie métricas de contador
• Crie métricas de distribuição

Para instrumentar a sua aplicação, recomendamos que use uma estrutura de instrumentação neutra em relação ao fornecedor e de código aberto, como o OpenTelemetry, em vez de APIs ou bibliotecas de cliente específicas do fornecedor e do produto. Para informações sobre a instrumentação da sua aplicação, consulte o artigo Instrumentação e observabilidade.

Nota: as métricas definidas pelo utilizador são uma funcionalidade faturável do Cloud Monitoring e podem existir custos para estas métricas. Para informações sobre preços, consulte as secções do Cloud Monitoring na página de preços da observabilidade do Google Cloud.

Antes de começar

Para saber mais sobre as estruturas subjacentes a todas as métricas, consulte Métricas, séries cronológicas e recursos.

Para usar o Cloud Monitoring, tem de ter um Google Cloud projeto com a faturação ativada. Quando necessário, faça o seguinte:

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

2. Verify that billing is enabled for your Google Cloud project.

3. Certifique-se de que a API Monitoring está ativada. Para ver detalhes, consulte o artigo Ativar a API Monitoring.
4. Para aplicações executadas fora do Google Cloud, o seu projeto Google Cloud tem de autenticar a sua aplicação através de credenciais padrão da aplicação (ADC) locais. Para mais informações, consulte o artigo Configure o ADC para um ambiente no local ou outro fornecedor de nuvem.

Crie um tipo de métrica definida pelo utilizador

Para criar uma métrica definida pelo utilizador, define um objeto MetricDescriptor que especifica várias informações sobre a métrica ou escreve dados de métricas. Quando escreve dados de métricas, o Monitoring cria o descritor de métricas para si com base na estrutura dos dados que fornece. Para informações sobre a conceção de um descritor de métricas, consulte o artigo Descritores de métricas para métricas definidas pelo utilizador.

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

Se escrever dados de métricas quando um descritor de métricas para essa métrica definida pelo utilizador ainda não existir, é criado automaticamente um descritor de métricas. No entanto, este novo descritor de métricas pode não ser exatamente o que quer; a criação automática de descritores de métricas envolve algumas pressuposições e predefinições.

O Cloud Monitoring cria um novo MetricDescriptor quando o objeto TimeSeries incluído numa chamada para timeSeries.create faz referência a um objeto Metric que especifica um nome de tipo de métrica inexistente. O Cloud Monitoring usa as seguintes regras para preencher o campo MetricDescriptor:

• type: o tipo é copiado do campo type do 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: as etiquetas que aparecem no objeto Metric. Cada descritor de etiqueta no novo descritor de métrica tem os seguintes campos:
  • key: a chave da etiqueta no objeto Metric.
  • valueType: STRING
  • description: não definido
• metricKind: o tipo de métrica está definido como GAUGE, a menos que especifique o parâmetro metricKind do objeto TimeSeries. Quando especifica o metricKind, a nova métrica tem esse tipo. Só pode especificar os tipos GAUGE e CUMULATIVE.
• valueType: o tipo de valor é retirado do valor com tipo do Point que está a ser escrito. O tipo de valor tem de ser BOOL, INT64, DOUBLE ou DISTRIBUTION. Quando especifica um tipo de valor no campo valueType de TimeSeries, esse tipo tem de corresponder ao tipo de Point.
• unit: não definido
• description: "Auto created custom metric.".
• displayName: não definido

Numa única chamada timeSeries.create, pode incluir vários objetos TimeSeries que fazem referência ao mesmo tipo de métrica inexistente. Nesse caso, as etiquetas no novo descritor de métricas consistem na união de todas as etiquetas nos objetos Metric em todas as séries cronológicas nesta chamada para create.

Passo seguinte: consulte o artigo Escreva métricas definidas pelo utilizador.

Criação manual de descritores de métricas

Para criar um descritor de métricas, faça o seguinte:

1. Determine a estrutura do descritor de métricas. Para ajudar a tomar estas decisões, pode procurar as métricas incorporadas e consultar os respetivos dados de séries cronológicas:

   1. Escolha um nome da métrica para a sua métrica definida pelo utilizador.

   2. Escolha um nome a apresentar e uma descrição para a métrica. O nome a apresentar é usado na Google Cloud consola.

   3. Escolha um ou mais projetos nos quais definir a sua métrica definida pelo utilizador e escrever os respetivos dados de séries cronológicas. Quando precisa da mesma métrica em vários projetos, crie definições idênticas da métrica em cada projeto.

   4. Determine o tipo, o tipo de valor e (opcionalmente) as unidades da métrica. Nem todos os tipos de valores e tipos de métricas são suportados para métricas definidas pelo utilizador. Para mais informações sobre estes campos, consulte o artigo Tipos de valores e tipos de métricas.

   5. Escolha as etiquetas da métrica: os respetivos nomes, tipos de valores e descrições.

2. Determine os recursos monitorizados em relação aos quais os dados das métricas são escritos. Escolha a partir da lista seguinte:

   • aws_ec2_instance: Instância do Amazon EC2.
   • dataflow_job: Tarefa do Dataflow.
   • gae_instance: Instância do App Engine.
   • gce_instance: Instância do Compute Engine.
   • generic_node: Nó de computação especificado pelo utilizador.
   • generic_task: Tarefa definida pelo utilizador.
   • gke_container: Instância de contentor do GKE.
   • global: Use este recurso quando nenhum outro tipo de recurso for adequado. Para a maioria dos exemplos de utilização, generic_node ou generic_task são melhores opções do que global.
   • k8s_cluster: Cluster do Kubernetes.
   • k8s_container: Contentor do Kubernetes.
   • k8s_node: Nó do Kubernetes.
   • k8s_pod: Pod do Kubernetes.

3. Crie um objeto MetricDescriptor e, em seguida, transmita-o como um argumento para uma chamada ao método metricDescriptors.create.

Normalmente, é um erro chamar metricDescriptors.create com o mesmo nome de tipo que um descritor de métricas existente. No entanto, se todos os campos do objeto MetricDescriptor novo corresponderem exatamente aos campos do descritor existente, não se trata de um erro, mas não tem qualquer efeito.

No exemplo seguinte, cria uma métrica de indicador.

Protocolo

Para criar um descritor de métricas, use o método metricDescriptors.create. Pode executar este método através do widget do Explorador de APIs na página de referência do método. Consulte o Explorador de APIs para obter mais informações.

Seguem-se os parâmetros de exemplo para metricDescriptors.create:

• name (URL): projects/[PROJECT_ID]

• Corpo do pedido: 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": "GAUGE",
    "valueType": "DOUBLE",
    "unit": "{USD}",
    "labels": [
      {
        "key": "store_id",
        "valueType": "STRING",
        "description": "The ID of the store."
      },
    ],
  }
  

Forneça estes valores aos campos no widget, usando o ID do seu projeto em vez de [PROJECT_ID]:

Clique no botão Executar para executar o método.

Experimentar!

Nota: para ver o pedido como um comando curl, como um pedido HTTP ou em JavaScript, clique em Ecrã inteiro no APIs Explorer.

Quando cria uma nova métrica, o campo name no MetricDescriptor é ignorado e pode ser omitido. O método create devolve o novo descritor de métrica com o campo name preenchido, que, neste exemplo, seria o seguinte:

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

Por exemplo, se quiser obter o descritor de uma métrica, usa este nome.

C#

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

        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

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

import (
	"context"
	"fmt"
	"io"

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

// 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: %w", err)
	}

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

Java

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

// Your Google Cloud Platform project ID
final String projectId = System.getProperty("projectId");

try (final MetricServiceClient client = MetricServiceClient.create();) {
  ProjectName projectName = ProjectName.of(projectId);

  MetricDescriptor descriptor =
      MetricDescriptor.newBuilder()
          .setType(type)
          .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(projectName.toString())
          .setMetricDescriptor(descriptor)
          .build();

  descriptor = client.createMetricDescriptor(request);
  System.out.println("Created descriptor " + descriptor.getName());
}

Node.js

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

// 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';
async function createMetricDescriptor() {
  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}`);
  });
}
createMetricDescriptor();

PHP

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

use Google\Api\LabelDescriptor;
use Google\Api\MetricDescriptor;
use Google\Cloud\Monitoring\V3\Client\MetricServiceClient;
use Google\Cloud\Monitoring\V3\CreateMetricDescriptorRequest;

/**
 * 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 = 'projects/' . $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);
    $createMetricDescriptorRequest = (new CreateMetricDescriptorRequest())
        ->setName($projectName)
        ->setMetricDescriptor($descriptor);

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

Python

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

from google.api import label_pb2 as ga_label
from google.api import metric_pb2 as ga_metric
from google.cloud import monitoring_v3

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

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

gem "google-cloud-monitoring"
require "google/cloud/monitoring"

# 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 o artigo Resolva problemas de chamadas API se tiver dificuldades.

Passo seguinte: consulte o artigo Escreva métricas definidas pelo utilizador.

Escreva métricas definidas pelo utilizador

Só pode escrever dados em tipos de métricas para métricas definidas pelo utilizador. Para escrever os seus dados, use o método timeSeries.create. Quando o intervalo temporal existe, este método anexa um novo ponto de dados ao intervalo temporal existente. Quando a série cronológica não existe, este método cria-a e anexa os dados.

Escreve pontos de dados transmitindo uma lista de objetos TimeSeries a timeSeries.create. O tamanho máximo da lista é 200 e cada objeto na lista tem de especificar uma série cronológica diferente:

• Os valores dos campos metric e resource identificam um objeto TimeSeries específico. Estes campos representam o tipo de métrica dos dados e o recurso monitorizado a partir do qual os dados foram recolhidos.
• Omita os campos metricKind e valueType. Estes são ignorados quando escreve pontos de dados.

• Cada objeto TimeSeries tem de conter apenas um objeto Point:

  • O valor e o intervalo de tempo do ponto têm de ser consistentes com a definição do tipo de métrica. Para obter informações sobre os intervalos de tempo para diferentes tipos de métricas, consulte TimeInterval.
  • O intervalo de tempo do ponto tem de ser posterior a qualquer ponto já existente na série cronológica.
  • A hora de fim do intervalo não pode ser mais de 25 horas no passado nem mais de cinco minutos no futuro.

• Para escrever mais do que um ponto na mesma série cronológica, use uma chamada separada para o método timeSeries.create para cada ponto. Não escreva dados numa única série cronológica mais rapidamente do que um ponto a cada 5 segundos. Quando adiciona pontos de dados a diferentes séries cronológicas, não existe limitação de taxa.

Protocolo

Para escrever dados de métricas, use o método timeSeries.create. Pode executar este método através do widget do Explorador de APIs na página de referência do método. Consulte o Explorador de APIs para mais informações.

Para escrever um ponto na métrica stores/daily_sales criada na criação manual de descritores de métricas:

1. Aceda à página de referência para timeSeries.create.
2. Forneça os parâmetros abaixo ao widget do APIs Explorer.
3. Clique no botão Executar.

Use os seguintes parâmetros de exemplo:

• name: projects/[PROJECT_ID]

• corpo do pedido: inclua uma lista de objetos TimeSeries O exemplo seguinte tem apenas uma série cronológica na lista.

  Nota: Tem de alterar os valores project_id e endTime no corpo do pedido seguinte. Use o ID do seu projeto. O endTime tem de estar próximo da hora atual; date -Iseconds devolve a hora atual num formato utilizável.

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

Experimentar!

Nota: para ver o pedido como um comando curl, como um pedido HTTP ou em JavaScript, clique em Ecrã inteiro no APIs Explorer.

C#

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

        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

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

// 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, %w ", err)
	}
	return nil
}

Java

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

String projectId = System.getProperty("projectId");

// 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
try (final MetricServiceClient client = MetricServiceClient.create();) {
  client.createTimeSeries(request);
}
System.out.println("Done writing time series value.");

Node.js

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

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

async function writeTimeSeriesData() {
  /**
   * 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);
}
writeTimeSeriesData();

PHP

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

use Google\Api\Metric;
use Google\Api\MonitoredResource;
use Google\Cloud\Monitoring\V3\Client\MetricServiceClient;
use Google\Cloud\Monitoring\V3\CreateTimeSeriesRequest;
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 = 'projects/' . $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);
    $createTimeSeriesRequest = (new CreateTimeSeriesRequest())
        ->setName($projectName)
        ->setTimeSeries([$timeSeries]);

    $metrics->createTimeSeries($createTimeSeriesRequest);

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

Python

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

from google.cloud import monitoring_v3

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-c"
series.metric.labels["TestLabel"] = "My Label Data"
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

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

gem "google-cloud-monitoring"
require "google/cloud/monitoring"

# 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 o artigo Resolva problemas de chamadas API se tiver dificuldades.

Elimine métricas definidas pelo utilizador

Para eliminar uma métrica definida pelo utilizador, elimine o respetivo descritor de métricas. Não pode eliminar os dados de séries cronológicas armazenados no seu Google Cloud projeto. No entanto, se eliminar o descritor de métricas, os dados ficam inacessíveis. Os dados expiram e são eliminados de acordo com a política de retenção de dados.

Não é possível eliminar o descritor de métricas de uma métrica integrada.

Nota: a eliminação de um descritor de métricas torna os dados de séries cronológicas existentes inacessíveis. Se recriar um descritor de métricas eliminado, exatamente como era antes da eliminação, pode recuperar o acesso aos dados. Não dependa deste comportamento.

Para eliminar o descritor de métricas, chame o método metricDescriptors.delete.

Protocolo

Para eliminar um descritor de métrica, use o método metricDescriptors.delete. Pode executar este método através do widget do Explorador de APIs na página de referência do método. Consulte o Explorador de APIs para mais informações.

Para eliminar a métrica stores/daily_sales criada na Criação manual de descritores de métricas:

1. Aceda à página de referência para metricDescriptors.delete:

2. Forneça o nome do descritor de métricas ao widget do APIs Explorer:

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

3. Clique no botão Executar.

Experimentar!

Nota: para ver o pedido como um comando curl, como um pedido HTTP ou em JavaScript, clique em Ecrã inteiro no APIs Explorer.

C#

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

import (
	"context"
	"fmt"
	"io"

	monitoring "cloud.google.com/go/monitoring/apiv3"
	"cloud.google.com/go/monitoring/apiv3/v2/monitoringpb"
)

// 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: %w", err)
	}
	fmt.Fprintf(w, "Deleted metric: %q\n", name)
	return nil
}

Java

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

Node.js

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

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

async function deleteMetricDescriptor() {
  /**
   * 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);
}
deleteMetricDescriptor();

PHP

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

use Google\Cloud\Monitoring\V3\Client\MetricServiceClient;
use Google\Cloud\Monitoring\V3\DeleteMetricDescriptorRequest;

/**
 * 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);
    $deleteMetricDescriptorRequest = (new DeleteMetricDescriptorRequest())
        ->setName($metricPath);
    $metrics->deleteMetricDescriptor($deleteMetricDescriptorRequest);

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

Python

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

from google.cloud import monitoring_v3

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

Ruby

Para se autenticar no Monitoring, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

gem "google-cloud-monitoring"
require "google/cloud/monitoring"

# 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 o artigo Resolva problemas de chamadas API se tiver dificuldades.

Modifique uma métrica definida pelo utilizador

Para modificar uma métrica definida pelo utilizador, tem de atualizar o objeto MetricDescriptor que define a métrica. A única modificação suportada é a adição de etiquetas.

Para adicionar etiquetas a uma métrica definida pelo utilizador existente, use o método timeSeries.create e inclua as novas etiquetas com os dados de séries cronológicas. As etiquetas são adicionadas ao descritor de métricas quando as etiquetas que tenta escrever são válidas e o número total de etiquetas é inferior a 30.

Em seguida, os dados de séries cronológicas são escritos como se a etiqueta estivesse presente desde o início.

Se quiser fazer mais do que adicionar novas etiquetas, tem de eliminar e recriar o descritor de métricas. Neste caso, perde todos os dados de séries cronológicas recolhidos anteriormente para o descritor de métricas antigo. Consulte o artigo Elimine métricas definidas pelo utilizador para mais informações.

Não é possível mudar o nome de uma métrica.

O que se segue?

• Veja e faça a gestão da utilização de métricas
• Lista de métricas integradas
• Lista de recursos monitorizados