Use o agente Ops e o protocolo OpenTelemetry (OTLP)

Este documento descreve como pode usar o agente de operações e o recetor do protocolo OpenTelemetry (OTLP) para recolher métricas e rastreios definidos pelo utilizador a partir de aplicações instrumentadas através do OpenTelemetry e em execução no Compute Engine.

Este documento está organizado da seguinte forma:

• Uma vista geral que descreve os exemplos de utilização do recetor OTLP.
• Pré-requisitos para usar o recetor OTLP.
• Configurar o agente para usar o recetor OTLP.
• Usar o recetor para recolher métricas. Esta secção descreve como consultar as suas métricas do OpenTelemetry no Cloud Monitoring.
• Usar o recetor para recolher rastreios. Esta secção descreve como autorizar uma conta de serviço a escrever dados no Cloud Trace.

Vista geral da utilização do recetor OTLP

Com o recetor OTLP do agente de operações, pode fazer o seguinte:

• Instrumente a sua aplicação através de um dos SDKs específicos do idioma para o OpenTelemetry. Para informações sobre os idiomas suportados, consulte a instrumentação do OpenTelemetry. A combinação dos SDKs OpenTelemetry e do agente de operações faz o seguinte por si:
  • Recolha métricas OTLP da sua aplicação e envie-as para o Cloud Monitoring para análise.
  • Recolha intervalos OTLP (dados de rastreio) da sua aplicação e, em seguida, envie esses intervalos para o Cloud Trace para análise.
• Recolher rastreios de aplicações de terceiros com suporte incorporado para OTLP ou plug-ins com esse suporte, como o Nginx. O recetor OTLP no agente de operações pode recolher esses rastreios. Para ver um exemplo, consulte o módulo nginx do OpenTelemetry.
• Use a instrumentação personalizada do OpenTelemetry.
• Use a instrumentação automática do OpenTelemetry.

Pode usar o recetor para recolher métricas, rastreios ou ambos. Depois de o agente de operações recolher as suas métricas, pode usar as funcionalidades do Cloud Monitoring, incluindo gráficos, painéis de controlo e políticas de alerta, para monitorizar as suas métricas. Se a sua aplicação também enviar dados de rastreio, pode usar o Cloud Trace para analisar esses dados.

Vantagens

Antes da disponibilidade do plug-in OTLP para o agente de operações, as principais formas de instrumentar as suas aplicações para recolher métricas e rastreios definidos pelo utilizador incluíam o seguinte:

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

A utilização do OpenTelemetry com o recetor OTLP tem várias vantagens em relação a estes métodos, incluindo as seguintes:

• O OpenTelemetry é a substituição do OpenCensus. O projeto OpenCensus vai ser arquivado. Para mais informações, consulte o artigo O que é o OpenTelemetry?.
• A carregamento é controlado ao nível do agente, pelo que não tem de voltar a implementar as suas aplicações se a configuração do agente for alterada.
• As suas aplicações não precisam de configurar Google Cloud credenciais. Toda a autorização é processada ao nível do agente.
• O código da sua aplicação não contém código de monitorização nem de rastreio específico Google Cloud. Não tem de usar a API Monitoring nem a API Trace diretamente.
• A sua aplicação envia dados para o agente de operações e, se a aplicação falhar, os dados recolhidos pelo agente de operações não são perdidos.

Limitações

O ouvinte OTLP exposto pelo recetor do agente de operações suporta o transporte gRPC. O HTTP, que é usado principalmente para clientes JavaScript, não é suportado. Para mais informações sobre o protocolo OpenTelemetry, consulte os detalhes do protocolo.

O recetor OTLP não recolhe registos. Pode recolher registos através do agente de operações e de outros recetores, e pode incluir informações de registo em intervalos OTLP, mas o recetor OTLP não suporta a recolha direta de registos. Para obter informações sobre a utilização do agente de operações para recolher registos, consulte Configurações de registo.

Pré-requisitos

Para recolher métricas e rastreios OTLP através do recetor OTLP e do agente Ops, tem de instalar o agente Ops versão 2.37.0 ou superior.

Este documento pressupõe que já tem uma aplicação baseada no OpenTelemetry escrita através de um dos SDKs do OpenTelemetry. Este documento não aborda a utilização de SDKs OpenTelemetry. Para informações sobre os SDKs e os idiomas suportados, consulte o artigo Instrumentação do OpenTelemetry.

Configure o agente de operações

Para configurar o agente Ops para usar o recetor OTLP, faça o seguinte:

1. Modifique o ficheiro de configuração do utilizador para o agente de operações de modo a incluir o recetor OTLP.
2. Reinicie o Ops Agent.

As secções seguintes descrevem cada passo.

Modifique o ficheiro de configuração do utilizador do agente de operações

Adicione os elementos de configuração do recetor OTLP ao ficheiro de configuração do utilizador do agente de operações:

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

Para ver informações gerais sobre a configuração do agente, consulte o Modelo de configuração.

O recetor OTLP apresenta a combinedsecção de configuração para o agente de operações. A utilização do recetor requer que configure serviços para métricas e rastreios, mesmo que não esteja a usar ambos.

As secções seguintes descrevem os passos de configuração do recetor OTLP.

Adicione a secção do destinatário combined

Coloca o recetor de métricas e rastreios OTLP na secção combined. Não são permitidos processadores nem serviços na secção combined. Não deve configurar nenhum outro destinatário com o mesmo nome de um destinatário na secção combined. O exemplo seguinte usa otlp como o nome do destinatário.

A configuração mínima do combined para OTLP tem o seguinte aspeto:

combined:
  receivers:
    otlp:
      type: otlp

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

• type: obrigatório. Tem de ser otlp
• grpc_endpoint: opcional. O ponto final gRPC no qual o recetor OTLP está à escuta. A predefinição é 0.0.0.0:4317.

• metrics_mode: opcional. O valor predefinido é googlemanagedprometheus, o que significa que o recetor envia métricas OTLP como métricas formatadas no formato Prometheus através da API Prometheus também usada pelo Managed Service for Prometheus.

  Para enviar as métricas como métricas personalizadas do Cloud Monitoring através da API Monitoring, defina a opção metrics_mode para o valor googlecloudmonitoring.

  Esta escolha afeta a forma como as suas métricas são carregadas e medidas para fins de faturação. Para mais informações sobre os formatos de métricas, consulte o artigo Formatos de carregamento para métricas OTLP.

Adicione pipelines OTLP aos seus serviços

O recetor OTLP pode recolher métricas e rastreios, pelo que tem de definir um serviço para métricas e para rastreios. Se não for recolher métricas nem rastreios, pode criar serviços vazios. Se já tiver serviços com outros pipelines, pode adicionar-lhes o pipeline OTLP.

A imagem seguinte mostra os serviços metrics e traces com o recetor OTLP incluído nos pipelines:

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

Se não quiser usar o serviço metrics nem o serviço traces para a recolha de OTLP, deixe o recetor de OTLP fora do pipeline do serviço. O serviço tem de existir, mesmo que não tenha pipelines. Se a sua aplicação enviar dados de um determinado tipo e não existir um pipeline correspondente que inclua o recetor, o agente de operações rejeita os dados.

Reinicie o agente de operações

Para aplicar as alterações de configuração, tem de reiniciar o agente de operações.

Recolha métricas OTLP

Quando usa o recetor OTLP para recolher métricas das suas aplicações OpenTelemetry, a principal escolha de configuração para o recetor é a API que quer usar para carregar as métricas.

Pode fazer esta escolha alterando a opção metrics_mode na configuração do recetor otlp ou usando o valor predefinido. A escolha afeta a forma como as suas métricas OTLP são carregadas no Cloud Monitoring e como esses dados são medidos para fins de faturação.

A escolha metrics_mode não afeta a sua capacidade de criar gráficos, painéis de controlo e políticas de alerta na monitorização.

• Para obter informações sobre como criar gráficos e painéis de controlo, consulte o artigo Vista geral dos painéis de controlo e gráficos.
• Para ver informações sobre políticas de alerta, consulte o artigo Vista geral dos alertas.

As secções seguintes descrevem as diferenças nos formatos usados pelos modos de métricas e como consultar os dados carregados para utilização na monitorização.

Formatos de carregamento para métricas OTLP

O recetor OTLP fornece a opção metrics_mode, que especifica a API usada para carregar os dados de métricas. Por predefinição, o recetor usa a API Prometheus; o valor predefinido para a opção metrics_mode é googlemanagedprometheus. As métricas são carregadas através da mesma API usada pelo Managed Service for Prometheus.

Pode configurar o recetor para enviar os dados das métricas para a API Cloud Monitoring. Para enviar dados para a API Monitoring, defina o valor da opção metrics_mode como googlecloudmonitoring, conforme mostrado no exemplo seguinte:

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

O formato de carregamento que usa determina como as métricas OTLP são mapeadas para o Cloud Monitoring. Pode criar gráficos, painéis de controlo e políticas de alerta no Monitoring para métricas de qualquer formato de métrica, mas refere-se às métricas de forma diferente nas consultas.

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

As secções seguintes descrevem os preços, as diferenças estruturais entre uma métrica carregada pela API Prometheus e a mesma métrica carregada pela API Monitoring, e como consultar as métricas.

Preços e quota

O formato de carregamento que usa determina a forma como as métricas OTLP são cobradas:

• API Prometheus: quando usa a API Prometheus para carregar as métricas da sua aplicação, os dados estão sujeitos a preços baseados em amostras, como se as métricas tivessem sido recebidas através do Managed Service for Prometheus.

  • Para ver os preços atuais, consulte o resumo dos preços do Cloud Monitoring.
  • Para mais informações sobre a contagem de amostras e a estimativa de custos, consulte o artigo Métricas cobradas por amostras carregadas.

• API Monitoring: quando usa a API Monitoring para carregar as métricas da sua aplicação, os dados estão sujeitos a preços baseados no volume, como os dados de outras integrações com o agente de operações.

  • Para ver os preços atuais, consulte o resumo dos preços do Cloud Monitoring.
  • Para mais informações sobre o volume de carregamento e a estimativa de custos, consulte o artigo Métricas cobradas por bytes carregados.

As métricas carregadas através do recetor OTLP são consideradas tipos de métricas "personalizadas" quando carregadas no Cloud Monitoring e estão sujeitas às quotas e aos limites das métricas personalizadas.

Estrutura de métricas

O Cloud Monitoring descreve o formato dos dados de métricas através de um esquema denominado descritor de métricas. O descritor de métricas inclui o nome da métrica, o tipo de dados dos valores das métricas, a forma como cada valor está relacionado com os valores anteriores e quaisquer etiquetas associadas aos valores. Se configurar o recetor OTLP para introduzir métricas através da API Prometheus, o descritor de métricas criado difere do descritor de métricas criado quando usa a API Monitoring.

API Prometheus: quando usa a API Prometheus para carregar as métricas da sua aplicação, cada métrica é transformada através da transformação OpenTelemetry para Prometheus padrão e mapeada para um tipo de recurso monitorizado do Cloud Monitoring.

• A transformação inclui as seguintes alterações:
  • O nome da métrica OTLP tem o prefixo da string prometheus.googleapis.com/.
  • Todos os carateres não alfanuméricos, como pontos finais (.), no nome da métrica OTLP são substituídos por sublinhados (_).
  • O nome da métrica OTLP tem o sufixo de 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 do recurso host.name.
  • machine_type: o valor do atributo do recurso host.type.

• O recurso monitorizado registado com as medições de métricas é do tipo genérico prometheus_target. A série cronológica do Prometheus gerada inclui as seguintes etiquetas do recurso prometheus_target, preenchidas com valores do recurso OTLP:

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

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

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

Se os dados OTLP recebidos não tiverem os atributos de recursos usados para os valores das etiquetas, os valores são retirados das informações sobre a VM que executa o agente do Google Cloud Operations. Este comportamento significa que os dados OTLP sem estes atributos de recursos aparecem com as mesmas etiquetas que os dados recolhidos pelo recetor do Ops Agent Prometheus.

API Monitoring: quando usa a API Monitoring para carregar as métricas da sua aplicação, cada métrica é processada da seguinte forma:

• O nome da métrica OTLP tem o prefixo da string workload.googleapis.com/, a menos que já contenha esta string ou outro domínio de métrica válido, como custom.googleapis.com. Recomendamos que use o domínio "workload".
• O recurso monitorizado registado com as medições de métricas é o tipo de máquina virtual do Compute Engine gce_instance.

Os exemplos seguintes mostram os descritores de métricas para um par de métricas do OpenTelemetry. As métricas são criadas por uma aplicação que usa a biblioteca de métricas Go OpenTelemetry. O separador API Prometheus mostra o descritor de métricas criado quando o recetor OTLP usa o modo de métricas Prometheus predefinido. O separador API Monitoring mostra o descritor de métricas criado quando o recetor OTLP usa o modo de métricas googlecloudmonitoring.

Nada se altera na aplicação que cria a métrica. A única alteração é o modo de métrica usado pelo recetor OTLP.

A aplicação cria uma métrica de indicador OTLP, otlp.test.gauge, que regista valores de ponto flutuante de 64 bits. Os separadores seguintes mostram o descritor de métricas que cada API de carregamento cria:

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

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

A aplicação cria uma métrica de contador OTLP, otlp.test.cumulative, que regista valores de ponto flutuante de 64 bits crescentes. Os separadores seguintes mostram o descritor de métricas que cada API de carregamento cria:

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

{
  "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 seguinte resume algumas das diferenças de formato impostas pelas APIs usadas para carregar métricas OTLP:

Formatos de carregamento e consultas

O modo de métricas usado no recetor OTLP afeta a forma como consulta as métricas resultantes no Cloud Monitoring quando cria gráficos, painéis de controlo e políticas de alerta.

Quando configura um gráfico, um painel de controlo ou uma política de alertas no Cloud Monitoring, a configuração inclui uma consulta para os dados nos quais o gráfico, o painel de controlo ou a política de alertas opera.

O Cloud Monitoring suporta as seguintes ferramentas para consultar dados de métricas:

• Uma interface baseada no criador de consultas incorporada em ferramentas como o explorador de métricas, a interface do criador de painéis de controlo e a interface de configuração de políticas de alerta.
• Linguagem de consulta Prometheus (PromQL): a linguagem de consulta baseada em texto usada pelo Prometheus de código aberto.

Para obter informações sobre como consultar métricas OTLP através destas ferramentas, consulte o seguinte:

• Consulte métricas OTLP carregadas através da API Prometheus
• Consulte as métricas OTLP carregadas através da API Monitoring

Consulte métricas OTLP carregadas através da API Prometheus

Esta secção ilustra como consultar as métricas OTLP carregadas através da API Prometheus, que é o modo de métricas predefinido para o recetor OTLP.

As consultas baseiam-se nas métricas OTLP descritas na estrutura de métricas:

• otlp.test.gauge: uma métrica de indicador OTLP que regista valores de ponto flutuante de 64 bits.
• otlp.test.cumlative: uma métrica de contador OTLP que regista valores de vírgula flutuante de 64 bits crescentes.

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

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

As métricas carregadas através da API Prometheus são escritas em relação ao tipo de recurso monitorizado prometheus_target.

Os separadores mostram o aspeto das consultas básicas quando consulta as métricas através da Google Cloud consola. Estes exemplos usam o explorador de métricas, mas os princípios são os mesmos para os painéis de controlo e as políticas de alertas.

Consulte métricas OTLP carregadas através da API Monitoring

Esta secção ilustra como consultar as métricas OTLP carregadas através da API Monitoring. Selecione a API Cloud Monitoring definindo o campo metrics_mode do recetor OTLP para o valor googlecloudmonitoring.

As consultas baseiam-se nas métricas OTLP descritas na estrutura de métricas:

• otlp.test.gauge: uma métrica de indicador OTLP que regista valores de ponto flutuante de 64 bits.
• otlp.test.cumlative: uma métrica de contador OTLP que regista valores de vírgula flutuante de 64 bits crescentes.

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

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

As métricas carregadas através da API Monitoring são escritas no tipo de recurso gce_instance monitored-resource.

Os separadores mostram o aspeto das consultas básicas quando consulta as métricas através da Google Cloud consola. Estes exemplos usam o explorador de métricas, mas os princípios são os mesmos para os painéis de controlo e as políticas de alertas.

Veja a utilização de métricas e os diagnósticos no Cloud Monitoring

A página Gestão de métricas do Cloud Monitoring fornece informações que podem ajudar a controlar o valor gasto em métricas faturáveis sem afetar a observabilidade. A página Gestão de métricas apresenta as seguintes informações:

• Volumes de carregamento para a faturação baseada em bytes e em amostras, em domínios de métricas e para métricas individuais.
• Dados sobre as etiquetas e a cardinalidade das métricas.
• Número de leituras para cada métrica.
• Utilização de métricas em políticas de alerta e painéis de controlo personalizados.
• Taxa de erros de escrita de métricas.

Também pode usar a página Gestão de métricas para excluir métricas desnecessárias, eliminando o custo da respetiva ingestão.

Para ver a página Gestão de métricas, faça o seguinte:

1. Na Google Cloud consola, aceda à página query_stats Gestão de métricas:

   Aceda a Gestão de métricas

   Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

2. Na barra de ferramentas, selecione o intervalo de tempo. Por predefinição, a página Gestão de métricas apresenta informações sobre as métricas recolhidas no dia anterior.

Para mais informações sobre a página Gestão de métricas, consulte o artigo Veja e faça a gestão da utilização de métricas.

Recolha rastreios OTLP

Se configurou o agente de operações para recolher rastreios, mas não recebe rastreios no Cloud Trace quando executa a sua aplicação, pode ter de conceder uma função adicional à conta de serviço do Compute Engine que o agente usa. Por predefinição, a conta de serviço recebe as funções necessárias para escrever métricas e registos, mas não rastreios.

As secções seguintes descrevem como conceder à conta de serviço a autorização necessária do Cloud Trace.

Determine as funções concedidas à conta de serviço

Para ver as funções concedidas 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"

Pode ver um resultado semelhante ao seguinte:

ROLE
roles/logging.logWriter
roles/monitoring.metricWriter

Se o resultado incluir roles/cloudtrace.agent ou roles/cloudtrace.admin, significa que a conta de serviço tem autorização suficiente para escrever rastreios. Para conceder uma destas funções à conta de serviço, consulte a secção seguinte.

Conceda a função do Cloud Trace à conta de serviço

Para uma conta de serviço, a função Agente do Cloud Trace é geralmente adequada.roles/cloudtrace.agent Para conceder esta função à 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, pode executar 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"

O resultado agora inclui roles/cloudtrace.agent:

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

Para mais informações sobre a gestão de funções da IAM, consulte o artigo Gerir o acesso ao projeto, às pastas e às organizações.

Depois de autorizar a conta de serviço usada pelo agente de operações a escrever dados no Cloud Trace, quando executa a sua aplicação baseada no OpenTelemetry, os rastreios aparecem no Cloud Trace.

Desative o recetor OTLP

Se estiver a recolher métricas e rastreios OTLP através do agente de operações e quiser desativar a recolha de métricas ou rastreios, mas não de ambos, faça o seguinte:

1. Desative a recolha de métricas ou rastreios fazendo uma das seguintes alterações ao ficheiro de configuração do utilizador, config.yaml:

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

2. Reinicie o Ops Agent.

Para desativar a recolha de métricas e rastreios OTLP pelo agente de operações, faça o seguinte:

1. Remova a configuração OTLP do ficheiro de configuração do utilizador:

   • Eliminar a secção combined completa, que inclui o otlp recetor.
   • Remova o pipeline otlp do serviço metrics.
   • Eliminar todo o serviço traces.

2. Reinicie o Ops Agent.

O que se segue?

Depois de as métricas e os rastreios da aplicação serem carregados, pode usar a consola para monitorizar e analisar os seus dados. Google Cloud

• Para ver informações sobre os painéis de controlo e os tipos de gráficos que pode criar, consulte o artigo Painéis de controlo e gráficos.
• Para obter informações sobre as políticas de alerta, consulte o artigo Usar políticas de alerta.
• Para obter informações sobre a análise de dados de rastreio, consulte o artigo Encontre e explore rastreios.