Usar o Agente de operações e o protocolo do OpenTelemetry (OTLP)

Neste documento, descrevemos como usar o Agente de operações e o receptor OpenTelemetry Protocol (OTLP, na sigla em inglês) para coletar métricas e traces definidos pelo usuário nos aplicativos instrumentados usando o OpenTelemetry e em execução no Compute Engine.

Este documento é organizado da seguinte maneira:

• Uma visão geral que descreve os casos de uso do receptor OTLP.
• Pré-requisitos para usar o receptor OTLP.
• Como configurar o agente para usar o receptor OTLP.
• Como usar o receptor para coletar métricas. Nesta seção, descrevemos como consultar suas métricas do OpenTelemetry no Cloud Monitoring.
• Como usar o receptor para coletar traces. Esta seção descreve como autorizar uma conta de serviço a gravar dados no Cloud Trace.

Visão geral do uso do receptor OTLP

Com o receptor OTLP do Agente de operações, é possível realizar as seguintes ações:

• Instrumentar seu aplicativo usando um dos SDKs de linguagem específica para o OpenTelemetry. Para mais informações sobre as linguagens compatíveis, consulte Instrumentação do OpenTelemetry. A combinação de SDKs do OpenTelemetry e do Agente de operações realizam as seguintes ações para você:
  • Coletar métricas OTLP do seu aplicativo e enviar essas métricas ao Cloud Monitoring para análise.
  • Coletar períodos OTLP (dados de trace) do aplicativo e enviar esses períodos ao Cloud Trace para análise.
• Coletar traces de aplicativos de terceiros com suporte integrado ao OTLP ou plug-ins com esse suporte, aplicativos como o Nginx. O receptor OTLP no Agente de operações pode coletar esses traces. Para ver um exemplo, consulte o módulo nginx do OpenTelemetry.
• Usar a instrumentação personalizada do OpenTelemetry.
• Usar a instrumentação automática do OpenTelemetry.

É possível usar o receptor para coletar métricas, traces ou ambos. Depois que o Agente de operações coleta as métricas, é possível usar os recursos do Cloud Monitoring para monitorá-las, como gráficos, painéis e políticas de alertas. Se o aplicativo também enviar dados de trace, será possível usar o Cloud Trace para analisar esses dados.

Benefícios

Antes da disponibilidade do plug-in OTLP para o Agente de operações, as principais maneiras de instrumentar seus aplicativos para coletar métricas e traces definidos pelo usuário incluíam estas ações:

• Usar bibliotecas de cliente que implementam a API Monitoring ou a API Trace.
• Usar as bibliotecas mais antigas do OpenCensus.

Usar o OpenTelemetry com o receptor OTLP tem vários benefícios em relação a esses métodos, como estes:

• O OpenTelemetry é o substituto do OpenCensus. O projeto do OpenCensus está sendo arquivado. Para mais informações, consulte O que é o OpenTelemetry?.
• A ingestão é controlada no nível do agente. Portanto, não será necessário reimplantar os aplicativos se a configuração do agente for alterada.
• Seus aplicativos não precisam configurar as credenciais do Google Cloud. Toda a autorização é processada no nível do agente.
• O código do aplicativo não contém código de monitoramento ou rastreamento específico do Google Cloud. Não é necessário usar a API Monitoring ou a API Trace diretamente.
• O aplicativo envia dados para o Agente de operações e, se ele falhar, os dados coletados por ele não serão perdidos.

Limitações

O listener OTLP exposto pelo receptor do Agente de operações é compatível com o transporte do gRPC. O HTTP, que é usado principalmente para clientes JavaScript, não é compatível. Para mais informações sobre o protocolo OpenTelemetry, consulte Detalhes do protocolo.

O receptor OTLP não coleta registros. É possível coletar registros usando o Agente de operações e outros receptores e incluir informações de registro nos períodos OTLP, mas o receptor OTLP não é compatível com a coleta direta de registros. Para informações sobre como usar o Agente de operações para coletar registros, consulte Configurações do Logging.

Pré-requisitos

Para coletar métricas e traces do OTLP usando o receptor OTLP e o Agente de operações, é necessário instalar o Agente de operações versão 2.37.0 ou posterior.

Neste documento, presumimos que você já tem um aplicativo baseado no OpenTelemetry gravado usando um dos SDKs do OpenTelemetry. Este documento não abrange o uso de SDKs do OpenTelemetry. Para mais informações sobre SDKs e as linguagens compatíveis, consulte Instrumentação do OpenTelemetry.

Configurar o agente de operações

Para configurar o Agente de operações a fim de usar o receptor OTLP, realize as seguintes ações:

1. Modifique o arquivo de configuração do usuário para que o Agente de operações inclua o receptor OTLP.
2. Reinicie o Agente de operações.

Descrevemos cada etapa nas próximas seções.

Modificar o arquivo de configuração do usuário do Agente de operações

Adicione os elementos de configuração do receptor OTLP ao arquivo de configuração do usuário do Agente de operações:

• No Linux: /etc/google-cloud-ops-agent/config.yaml
• No Windows: C:\Program Files\Google\Cloud Operations\Ops Agent\config\config.yaml

Para informações gerais sobre como configurar o agente, consulte Modelo de configuração.

O receptor OTLP apresenta a seção de configuração combined do Agente de operações. O uso do receptor requer a configuração de serviços para métricas e traces, mesmo que você não esteja usando ambos.

Descrevemos as etapas de configuração do receptor OTLP nas próximas seções.

Adicionar a seção do receptor combined

Coloque o receptor de métricas e traces OTLP na seção combined. Nenhum processador ou serviço é permitido na seção combined. Não é necessário configurar outro receptor com o mesmo nome de um receptor na seção combined. O exemplo a seguir usa otlp como o nome do receptor.

A configuração combined mínima para o OTLP é semelhante a esta:

combined:
  receivers:
    otlp:
      type: otlp

O receptor otlp tem as seguintes opções de configuração:

• type: obrigatório. Precisa ser otlp.
• grpc_endpoint: opcional. O endpoint gRPC em que o receptor OTLP ouve. O padrão é 0.0.0.0:4317.

• metrics_mode: opcional. O padrão é googlemanagedprometheus, o que significa que o receptor envia métricas OTLP como métricas formatadas pelo Prometheus usando a API Prometheus, também usada pelo Managed Service para Prometheus.

  Para enviar as métricas como métricas personalizadas do Cloud Monitoring usando a API Monitoring, defina a opção metrics_mode com o valor googlecloudmonitoring.

  Essa opção afeta o modo como as métricas são ingeridas e avaliadas no faturamento. Para mais informações sobre formatos de métricas, consulte Formatos de ingestão para métricas OTLP.

Adicionar pipelines OTLP aos serviços

O receptor OTLP pode coletar métricas e traces, mas você precisa definir um serviço para métricas e traces. Se você não for coletar métricas ou traces, crie serviços vazios. Se você já tiver serviços com outros pipelines, adicione o pipeline OTLP a eles.

Veja a seguir os serviços metrics e traces com o receptor OTLP incluso nos pipelines:

combined:
  receivers:
    otlp:
      type: otlp
metrics:
  service:
    pipelines:
      otlp:
        receivers: [otlp]
traces:
  service:
    pipelines:
      otlp:
        receivers: [otlp]

Se você não quiser usar o serviço metrics ou traces para a coleta OTLP, deixe o receptor OTLP fora do pipeline do serviço. O serviço precisa existir, mesmo que não tenha pipelines. Se o aplicativo enviar dados de um determinado tipo e não houver um pipeline correspondente que inclua o receptor, o Agente de operações descartará os dados.

Reiniciar o agente de operações

Para aplicar as alterações de configuração, reinicie o Agente de operações.

Linux

1. Para reiniciar o agente, execute o seguinte comando na instância:

   sudo systemctl restart google-cloud-ops-agent
   

2. Para confirmar se o agente foi reiniciado, execute o seguinte comando e verifique se os componentes "Agente de métricas" e "Agente do Logging" foram iniciados:

   sudo systemctl status "google-cloud-ops-agent*"
   

Windows

1. Conecte-se à sua instância usando o RDP ou uma ferramenta semelhante e faça login no Windows.
2. Abra um terminal do PowerShell com privilégios de administrador clicando com o botão direito do mouse no ícone do PowerShell e selecionando Executar como administrador.
3. Para reiniciar o agente, execute o seguinte comando do PowerShell:

   Restart-Service google-cloud-ops-agent -Force
   

4. Para confirmar se o agente foi reiniciado, execute o seguinte comando e verifique se os componentes "Agente de métricas" e "Agente do Logging" foram iniciados:

   Get-Service google-cloud-ops-agent*
   

Coletar métricas OTLP

Quando você usa o receptor OTLP para coletar métricas dos seus aplicativos OpenTelemetry, a principal opção de configuração para o receptor é a API que você quer usar para ingerir as métricas.

Configure essa definição alterando a opção metrics_mode na configuração do receptor otlp ou usando o valor padrão. A opção afeta como as métricas OTLP são ingeridas no Cloud Monitoring e como esses dados são medidos para fins de faturamento.

Observação: o número e a cardinalidade das métricas emitidas pelo aplicativo são controlados por você. Não há um conjunto selecionado de métricas. A quantidade de dados ingeridos é determinada pelo aplicativo.

A escolha de metrics_mode não afeta sua capacidade de criar gráficos, painéis e políticas de alertas no Monitoring.

• Para informações sobre como criar gráficos e painéis, consulte Visão geral de gráficos e painéis.
• Para informações sobre políticas de alertas, consulte Visão geral de alertas.

Nas próximas seções, descrevemos as diferenças nos formatos usados pelos modos de métrica e como consultar os dados ingeridos para uso no Monitoring.

Formatos de ingestão para métricas OTLP

O receptor OTLP oferece a opção metrics_mode, que especifica a API usada para ingerir os dados de métrica. Por padrão, o receptor usa a API Prometheus. O valor padrão da opção metrics_mode é googlemanagedprometheus. As métricas são ingeridas com a mesma API usada pelo Managed Service para Prometheus.

É possível configurar o receptor para enviar os dados de métrica para a API Cloud Monitoring. Para enviar dados à API Monitoring, defina o valor da opção metrics_mode como googlecloudmonitoring, conforme mostrado no exemplo a seguir:

combined:
  receivers:
    otlp:
      type: otlp
      metrics_mode: googlecloudmonitoring

O formato de ingestão usado determina como as métricas OTLP são mapeadas no Cloud Monitoring. É possível criar gráficos, painéis e políticas de alertas no Monitoring para métricas de qualquer formato, mas, nas consultas, você se refere às métricas de maneira diferente.

O formato de ingestão também determina o modelo de preços usado para a ingestão de dados.

Nas próximas seções, descrevemos os preços, as diferenças estruturais entre uma métrica ingerida pela API Prometheus e a mesma métrica ingerida pela API Monitoring e como se referir às métricas nas consultas.

Preços e cotas

O formato de ingestão usado determina como as métricas OTLP são cobradas:

• API Prometheus: quando você usa a API Prometheus para ingerir as métricas do aplicativo, os dados estão sujeitos a preços baseados em amostra, como se as métricas tivessem chegado via Managed Service para Prometheus.

  • Para preços atuais, consulte Resumo de preços do Cloud Monitoring.
  • Para mais informações sobre como contar amostras e estimar custos, consulte Exemplos de preços com base em amostras ingeridas.

• API Monitoring: quando você usa a API Monitoring para ingerir as métricas do aplicativo, os dados estão sujeitos a preços baseados em volume, como dados de outras integrações com o Agente de operações.

  • Para preços atuais, consulte Resumo de preços do Cloud Monitoring.
  • Para mais informações sobre o volume de ingestão e a estimativa de custos, consulte Exemplos de preços baseados em bytes ingeridos.

As métricas ingeridas usando o receptor OTLP são consideradas tipos de métricas "personalizadas" quando ingeridas no Cloud Monitoring e estão sujeitas a cotas e limites para métricas personalizadas.

Estrutura da métrica

O Cloud Monitoring descreve o formato dos dados de métrica usando um esquema chamado descritor de métrica. O descritor de métrica inclui o nome da métrica, o tipo de dados de valores de métrica, como cada valor está relacionado aos valores anteriores e qualquer etiqueta associada aos valores. Se você configurar o receptor OTLP para ingerir métricas usando a API Prometheus, o descritor de métrica criado será diferente daquele que você criou ao usar a API Monitoring.

API Prometheus: quando você usa a API Prometheus para ingerir as métricas do aplicativo, cada métrica é transformada usando a transformação OpenTelemetry-to-Prometheus padrão e mapeada para um tipo de recurso monitorado do Cloud Monitoring.

• A transformação inclui as seguintes alterações:
  • O nome da métrica OTLP é prefixado com a string prometheus.googleapis.com/.
  • Todos os caracteres não alfanuméricos, como pontos (.), no nome da métrica OTLP são substituídos por sublinhados (_).
  • O nome da métrica OTLP é sufixado com uma string que indica o tipo de métrica, como /gauge ou /counter.
• As seguintes etiquetas, preenchidas com valores do recurso OTLP, são adicionadas à métrica:
  • instance_name: o valor do atributo de recurso host.name.
  • machine_type: o valor do atributo de recurso host.type.

• O recurso monitorado registrado com as medições métricas é o tipo genérico prometheus_target. A série temporal gerada do Prometheus contém as seguintes etiquetas do recurso prometheus_target, preenchido com valores do recurso OTLP:

  • location: o valor do atributo de recurso cloud.availability_zone.
  • namespace: o valor do atributo de recurso host.id.

  O tipo de recurso prometheus_target também contém estas etiquetas:

  • project_id: o identificador do projeto do Google Cloud, como my-project, em que o Agente de operações está em execução.
  • cluster: o valor é sempre __gce__ quando as métricas são coletadas pelo Agente de operações.

Se os dados OTLP recebidos não tiverem os atributos de recurso usados para os valores de etiqueta, os valores serão extraídos das informações sobre a VM em execução no Agente de operações. Esse comportamento significa que os dados OTLP sem esses atributos de recurso aparecem com as mesmas etiquetas que os dados coletados pelo receptor Prometheus do Agente de operações.

API Monitoring: quando você usa a API Monitoring para ingerir as métricas do aplicativo, cada uma é processada da seguinte maneira:

• O nome da métrica do OTLP é prefixado com a string workload.googleapis.com/, a menos que já contenha essa string ou outro domínio de métrica válido, como custom.googleapis.com. Recomendamos usar o domínio de carga de trabalho "workload".
• O recurso monitorado registrado com as medições métricas é o tipo de máquina virtual do Compute Engine gce_instance.

Os exemplos a seguir mostram os descritores de métrica de um par de métricas do OpenTelemetry. As métricas são criadas por um aplicativo que usa a biblioteca de métricas do OpenTelemetry em Go. A guia API Prometheus mostra o descritor de métrica criado quando o receptor OTLP usa o modo de métricas padrão do Prometheus. A guia API Monitoring mostra o descritor de métrica criado quando o receptor OTLP usa o modo de métrica googlecloudmonitoring.

Nada muda no aplicativo que cria a métrica. A única alteração é o modo de métrica usado pelo receptor OTLP.

O aplicativo cria uma métrica de medidor OTLP, otlp.test.gauge, que registra valores de pontos flutuantes de 64 bits. As guias a seguir mostram o descritor de métrica que cada API de ingestão cria:

API Prometheus

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_gauge/gauge",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_gauge/gauge",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

API Monitoring

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.gauge",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "GAUGE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.gauge",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

O aplicativo cria uma métrica de contador OTLP, otlp.test.cumulative, que registra valores crescentes de pontos flutuantes de 64 bits. As guias a seguir mostram o descritor de métrica que cada API de ingestão cria:

API Prometheus

{
  "name": "projects/PROJECT_ID/metricDescriptors/prometheus.googleapis.com/otlp_test_cumulative/counter",
  "labels": [
    {
      "key": "instance_name"
    },
    {
      "key": "machine_type"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "prometheus.googleapis.com/otlp_test_cumulative/counter",
  "monitoredResourceTypes": [
    "prometheus_target"
  ]
}

API Monitoring

{
  "name": "projects/PROJECT_ID/metricDescriptors/workload.googleapis.com/otlp.test.cumulative",
  "labels": [
    {
      "key": "instrumentation_source"
    }
  ],
  "metricKind": "CUMULATIVE",
  "valueType": "DOUBLE",
  "type": "workload.googleapis.com/otlp.test.cumulative",
  "monitoredResourceTypes": [
    "gce_instance",
    ...many other types deleted...
  ]
}

A tabela a seguir resume algumas das diferenças de formato impostas pelas APIs usadas para ingerir métricas OTLP:

	API Prometheus	API Monitoring
Domínio da métrica	prometheus.googleapis.com	workload.googleapis.com
Nome da métrica OTLP	Modificado durante a ingestão	Usado conforme fornecido
Recurso monitorado	prometheus_target	gce_instance

Consultas e formatos de ingestão

O modo de métricas usado no receptor OTLP afeta o jeito de consultar as métricas resultantes no Cloud Monitoring ao criar gráficos, painéis e políticas de alertas.

Quando você configura um gráfico, um painel ou uma política de alertas no Cloud Monitoring, a configuração inclui uma consulta dos dados em que o gráfico, o painel ou a política de alertas opera.

O Cloud Monitoring é compatível com as seguintes ferramentas para consultar dados de métrica:

• Uma interface baseada em builder de consulta integrada a ferramentas como o Metrics Explorer, a interface do builder de painel e a interface de configuração de política de alertas.
• Linguagem de consulta do Monitoring (MQL, na sigla em inglês): uma linguagem de consulta baseada em texto específica do Cloud Monitoring.
• Linguagem de consulta do Prometheus (PromQL, na sigla em inglês): a linguagem de consulta baseada em texto usada pelo Prometheus de código aberto.

Para informações sobre como consultar métricas OTLP usando essas ferramentas, acesse estes links:

• Consultar métricas OTLP ingeridas usando a API Prometheus
• Consultar métricas OTLP ingeridas usando a API Monitoring

Consultar métricas OTLP ingeridas usando a API Prometheus

Nesta seção, ilustramos como consultar métricas OTLP ingeridas usando a API Prometheus, que é o modo de métrica padrão do receptor OTLP.

As consultas são baseadas nas métricas OTLP descritas em Estrutura da métrica:

• otlp.test.gauge: uma métrica de medidor OTLP que registra valores de pontos flutuantes de 64 bits.
• otlp.test.cumlative: uma métrica de contador OTLP que registra valores crescentes de pontos flutuantes de 64 bits.

Essas métricas são ingeridas no Cloud Monitoring com os seguintes tipos de métrica, que funcionam como nomes:

• prometheus.googleapis.com/otlp_test_gauge/gauge
• prometheus.googleapis.com/otlp_test_cumulative/counter

As métricas ingeridas usando a API Prometheus são gravadas em relação ao tipo de recurso monitorado prometheus_target.

As guias mostram a aparência das consultas básicas ao consultar as métricas usando o console do Google Cloud. Esses exemplos usam o Metrics Explorer, mas os princípios são os mesmos para painéis e políticas de alertas.

Interface do builder de consulta

Para usar uma interface do builder de consulta para consultar dados de métrica, especifique o tipo de métrica e o tipo de recurso monitorado digitando nos campos ativados para pesquisa. Há bem menos tipos de recurso do que tipos de métrica. Por isso, é mais eficiente no geral pesquisar o tipo de recurso e depois usar o menu de métricas associadas para encontrar o tipo de métrica.

Se você digitar "prometheus" no campo de pesquisa, os resultados incluirão o recurso monitorado prometheus_target, mostrado pelo nome de exibição "Prometheus Target" e o conjunto de métricas gravadas no recurso. As métricas são categorizadas por nome. As duas métricas de exemplo aparecem com a categoria Otlp. É possível selecionar Prometheus/otlp_test_cumulative/counter ou Prometheus/otlp_test_gauge/gauge.

Para mais informações sobre como usar o builder de consulta, veja Criar consultas usando menus.

A captura de tela a seguir mostra o resultado ao consultar a métrica prometheus.googleapis.com/otlp_test_gauge/gauge:

A captura de tela a seguir mostra o resultado ao consultar a métrica prometheus.googleapis.com/otlp_test_cumulative/counter:

MQL

Para consultar dados de métrica usando MQL, use uma instrução fetch e especifique o tipo de métrica e o tipo de recurso monitorado, com :: entre eles. As consultas MQL comuns das métricas de exemplo são assim:

• fetch prometheus.googleapis.com/otlp_test_gauge/gauge::prometheus_target
• fetch prometheus.googleapis.com/otlp_test_cumulative/counter::prometheus_target

Para mais informações sobre como criar consultas MQL, consulte Exemplos de consultas MQL.

A captura de tela a seguir mostra o resultado ao consultar a métrica prometheus.googleapis.com/otlp_test_gauge/gauge:

A captura de tela a seguir mostra o resultado ao consultar a métrica prometheus.googleapis.com/otlp_test_cumulative/counter:

PromQL

Ao usar PromQL para consultar dados de métrica que foram ingeridos usando a API Prometheus, basta especificar a forma modificada do nome da métrica OTLP original. Não é preciso especificar a string prometheus.googleapis.com/ prefixada ou o tipo sufixado.

Quando a métrica pode ser gravada em relação a um só tipo de recurso monitorado, não é necessário especificar o recurso. Conforme descrito em Estrutura da métrica, as métricas OTLP ingeridas usando a API Prometheus são gravadas apenas em relação ao tipo de recurso monitorado prometheus_target. As consultas PromQL comuns das métricas de exemplo são assim:

• otlp_test_gauge
• otlp_test_cumulative

Para mais informações sobre como usar PromQL no Cloud Monitoring para consultar métricas ingeridas usando a API Prometheus, consulte Dados do Google Cloud Managed Service para Prometheus no Cloud Monitoring. Para mais informações sobre a linguagem PromQL, veja Como consultar o Prometheus.

A captura de tela a seguir mostra o resultado ao consultar a métrica prometheus.googleapis.com/otlp_test_gauge/gauge:

A captura de tela a seguir mostra o resultado ao consultar a métrica prometheus.googleapis.com/otlp_test_cumulative/counter:

Consultar métricas OTLP ingeridas usando a API Monitoring

Nesta seção, ilustramos como consultar métricas OTLP ingeridas usando a API Monitoring. Selecione a API Cloud Monitoring definindo o campo metrics_mode do receptor OTLP com o valor googlecloudmonitoring.

As consultas são baseadas nas métricas OTLP descritas em Estrutura da métrica:

• otlp.test.gauge: uma métrica de medidor OTLP que registra valores de pontos flutuantes de 64 bits.
• otlp.test.cumlative: uma métrica de contador OTLP que registra valores crescentes de pontos flutuantes de 64 bits.

Essas métricas são ingeridas no Cloud Monitoring com os seguintes tipos de métrica, que funcionam como nomes:

• workload.googleapis.com/otlp.test.gauge
• workload.googleapis.com/otlp.test.cumulative

As métricas ingeridas usando a API Monitoring são gravadas em relação ao tipo de recurso monitorado gce_instance.

As guias mostram a aparência das consultas básicas ao consultar as métricas usando o console do Google Cloud. Esses exemplos usam o Metrics Explorer, mas os princípios são os mesmos para painéis e políticas de alertas.

Interface do builder de consulta

Para usar uma interface do builder de consulta para consultar dados de métrica, especifique o tipo de métrica e o tipo de recurso monitorado digitando nos campos ativados para pesquisa. Há bem menos tipos de recurso do que tipos de métrica. Por isso, é mais eficiente no geral pesquisar o tipo de recurso e depois usar o menu de métricas associadas para encontrar o tipo de métrica.

Se você digitar "gce_instance" no campo de pesquisa, os resultados mostrarão o tipo de recurso pelo nome de exibição, "VM Instance", e o conjunto de métricas gravadas no recurso. As métricas são categorizadas por nome. As duas métricas de exemplo aparecem com a categoria Otlp. É possível selecionar Workload/Workload/otlp_test_cumulative ou Workload/otlp_test_gauge.

Para mais informações sobre como usar o builder de consulta, veja Criar consultas usando menus.

A captura de tela a seguir mostra o resultado ao consultar a métrica workload.googleapis.com/otlp.test.gauge:

A captura de tela a seguir mostra o resultado ao consultar a métrica workload.googleapis.com/otlp.test.cumulative:

MQL

Para consultar dados de métrica usando MQL, use uma instrução fetch e especifique o tipo de métrica e o tipo de recurso monitorado, com :: entre eles. As consultas MQL comuns das métricas de exemplo são assim:

• fetch workload.googleapis.com/otlp.test.gauge::gce_instance
• fetch workload.googleapis.com/otlp.test.cumulative::gce_instance

Para mais informações sobre como criar consultas MQL, consulte Exemplos de consultas MQL.

A captura de tela a seguir mostra o resultado ao consultar a métrica workload.googleapis.com/otlp.test.gauge:

A captura de tela a seguir mostra o resultado ao consultar a métrica workload.googleapis.com/otlp.test.cumulative:

PromQL

Ao usar PromQL para consultar dados de métrica que foram ingeridos usando a API Monitoring, é necessário mapear o nome da métrica para as convenções em PromQL. As regras básicas de mapeamento incluem estas:

• Substitua o primeiro / por :.
• Substitua todos os outros caracteres especiais (incluindo . e outros caracteres /) por _.

Para mais informações sobre as regras de mapeamento, consulte Como mapear métricas do Cloud Monitoring para PromQL.

Os tipos das métricas de exemplo do Monitoring são mapeados para PromQL da seguinte maneira:

• workload_googleapis_com:otlp_test_gauge
• workload_googleapis_com:otlp_test_cumulative

Quando a métrica pode ser gravada em relação a um só tipo de recurso monitorado, não é necessário especificar o recurso. As métricas de exemplo são gravadas em relação ao tipo de recurso monitorado gce_instance, mas, conforme descrito em Estrutura da métrica, gce_instance é apenas um dos tipos de métrica possíveis. Portanto, as consultas PromQL dessas métricas precisam incluir um filtro para o tipo de recurso gce_instance. Para incluir o filtro, adicione a seguinte string no final dos nomes de métrica mapeados: {monitored_resource="gce_instance"}

Para mais informações sobre como usar PromQL no Cloud Monitoring, consulte PromQL no Cloud Monitoring. Para mais informações sobre a linguagem PromQL, veja Como consultar o Prometheus.

As consultas PromQL comuns das métricas de exemplo são assim:

• workload_googleapis_com:otlp_test_gauge{monitored_resource="gce_instance"}
• workload_googleapis_com:otlp_test_cumulative{monitored_resource="gce_instance"}

A captura de tela a seguir mostra o resultado ao consultar a métrica workload.googleapis.com/otlp.test.gauge:

A captura de tela a seguir mostra o resultado ao consultar a métrica workload.googleapis.com/otlp.test.cumulative:

Ver diagnósticos e uso de métricas no Cloud Monitoring

A página Gerenciamento de métricas do Cloud Monitoring fornece informações que podem ajudar a controlar o valor gasto em métricas sujeitas a cobrança, sem afetar a observabilidade. A página Gerenciamento de métricas mostra as seguintes informações:

• Volumes de ingestão para faturamento baseado em byte e amostra, em domínios de métricas e para métricas individuais.
• Dados sobre rótulos e cardinalidade de métricas.
• Uso de métricas em políticas de alertas e painéis personalizados.
• Taxa de erros de gravação de métrica.

Para visualizar a página Gerenciamento de métricas, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione Monitoramento e  Gerenciamento de métricas:

   Acesse Gerenciamento de métricas

2. Na barra de ferramentas, selecione a janela de tempo. Por padrão, a página Gerenciamento de métricas exibe informações sobre as métricas coletadas no dia anterior.

Para mais informações sobre a página Gerenciamento de métricas, consulte Ver e gerenciar o uso de métricas.

Coletar traces OTLP

Se você configurou o Agente de operações para coletar traces, mas não recebe traces no Cloud Trace ao executar o aplicativo, talvez seja necessário conceder mais um papel à conta de serviço do Compute Engine usada pelo agente. Por padrão, a conta de serviço recebe os papéis necessários para gravar métricas e registros, mas não traces.

Nas próximas seções, descrevemos como conceder a autorização necessária do Cloud Trace à conta de serviço.

Determinar os papéis concedidos à conta de serviço

Para ver os papéis concedidos a uma conta de serviço, execute o seguinte comando gcloud projects get-iam-policy:

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

A saída pode ser assim:

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

Se a saída incluir roles/cloudtrace.agent ou roles/cloudtrace.admin, a conta de serviço terá permissão suficiente para gravar traces. Para conceder um desses papéis à conta de serviço, consulte a próxima seção.

Conceder o papel do Cloud Trace à conta de serviço

Para uma conta de serviço, o papel de agente do Cloud Trace, roles/cloudtrace.agent, é geralmente apropriado. Para conceder esse papel à conta de serviço, execute o seguinte comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/cloudtrace.agent"

Em seguida, execute o comando gcloud projects get-iam-policy para verificar se a alteração foi feita:

gcloud projects get-iam-policy PROJECT_ID --format="table(bindings.role)" --flatten="bindings[].members" --filter="bindings.members:SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com"

A saída agora inclui roles/cloudtrace.agent:

ROLE
roles/cloudtrace.agent
roles/logging.logWriter
roles/monitoring.metricWriter

Para mais informações sobre como gerenciar papéis do IAM, consulte Gerenciar acesso a projeto, pastas e organizações.

Depois de autorizar a conta de serviço usada pelo Agente de operações a gravar dados no Cloud Trace, quando você executar o aplicativo baseado no OpenTelemetry, os traces aparecerão no Cloud Trace:

Desativar o receptor OTLP

Se você estiver coletando métricas e traces OTLP usando o Agente de operações e quiser desativar a coleta de métricas ou traces, mas não de ambos, realize as seguintes ações:

1. Desative a coleta de métricas ou traces fazendo uma das seguintes alterações no arquivo de configuração do usuário, config.yaml:

   • Remova o pipeline otlp do serviço metrics.
   • Remova o pipeline otlp do serviço traces.

2. Reinicie o Agente de operações.

Para desativar a coleta de métricas e traces OTLP do Agente de operações, realize as seguintes ações:

1. Remova a configuração OTLP do arquivo de configuração do usuário:

   • Exclua toda a seção combined, que inclui o receptor otlp.
   • Remova o pipeline otlp do serviço metrics.
   • Exclua todo o serviço traces.

2. Reinicie o Agente de operações.

A seguir

Após a ingestão das métricas e dos traces do aplicativo, use o console do Google Cloud para monitorar e analisar os dados.

• Para informações sobre painéis e os tipos de gráficos que podem ser criados, consulte Painéis e gráficos.
• Para informações sobre políticas de alertas, consulte Como usar políticas de alertas.
• Para informações sobre como analisar dados de trace, consulte Encontrar e explorar traces.