Esta página foi traduzida pela API Cloud Translation.

Instrumentar um aplicativo para o monitoramento de aplicativos

Este documento descreve como configurar um aplicativo do App Hub para que as métricas e os dados de rastreamento gerados por ele contenham rótulos específicos do aplicativo. Também descreve como fazer com que seu aplicativo exporte uma métrica usada pelo Application Monitoring para informar o nível de tráfego, a taxa de erros do servidor ou a latência para cargas de trabalho de solicitações HTTP executadas no Google Kubernetes Engine.

Sobre os rótulos específicos de aplicativos

Os identificadores específicos do aplicativo se referem a identificadores ou atributos injetados em dados de registro, métricas ou rastreamento. Esses rótulos identificam o serviço ou a carga de trabalho que gerou os dados. É possível usar rótulos específicos do aplicativo como qualquer outro rótulo. Por exemplo, é possível filtrar os dados pelo ID de um aplicativo. A telemetria gerada pela infraestrutura compatível inclui automaticamente esses rótulos. Com a instrumentação, as métricas e os traces gravados pelo aplicativo podem incluir esses rótulos.

Nesta seção, interprete a.b.{x,y} como a.b.x e a.b.y.

Os dados de métricas da instrumentação adicionada aos seus aplicativos podem incluir os seguintes rótulos de métricas:

metric.labels.apphub_application_{container,id,location}
metric.labels.apphub_workload_{criticality_type,environment_type,id}

Os períodos do Trace gerados pela instrumentação adicionada aos seus aplicativos podem incluir os seguintes atributos de recurso:

gcp.apphub.application.{container,id,location}
gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

Sobre as métricas do servidor HTTP do OpenTelemetry

Não há métricas de sistema para cargas de trabalho executadas no Google Kubernetes Engine que possam informar o nível de tráfego, a taxa de erros do servidor ou a latência para solicitações HTTP. No entanto, os valores desses indicadores de ouro podem ser derivados do http.server.request.duration, que é uma métrica coletada automaticamente pela biblioteca de cliente HTTP OpenTelemetry.

O exportador googlemanagedprometheus converte a métrica http.server.request.duration do OpenTelemetry em uma métrica do Prometheus com as seguintes propriedades:

Nome: prometheus/http_server_request_duration_seconds/histogram
Métrica: prometheus.googleapis.com/http_server_request_duration_seconds/histogram
Tipos de recurso: prometheus_target
Unidade: s
Tipo: CUMULATIVE
Tipo de valor: DISTRIBUTION

Quando o projeto Google Cloud contém a métrica http_server_request_duration_seconds, os painéis do Application Monitoring mostram o nível de tráfego, a taxa de erros do servidor e a latência das solicitações HTTP.

Para saber como configurar seu aplicativo para exportar a métrica http_server_request_duration_seconds, consulte a seção Usar o OpenTelemetry no Kubernetes deste documento.

Adicionar rótulos de aplicativo aos dados de métricas

O Google Cloud Observability tenta identificar a origem das métricas do Prometheus comparando os atributos anexados às métricas do Prometheus enviadas ao seu projeto com os dados retornados da API App Hub. O restante desta seção lista as configurações que permitem ao Google Cloud Observability identificar o aplicativo do App Hub.

Usar o OpenTelemetry no Kubernetes

Para que o Google Cloud Observability anexe rótulos de aplicativos aos dados de métricas gerados pelas cargas de trabalho do aplicativo executadas no Google Kubernetes Engine, faça o seguinte:

Instrumente o aplicativo com o OpenTelemetry.
- Para informações gerais, consulte Instrumentação e observabilidade.
- Para links de amostras em Go, Java, Node.js e Python, além de informações sobre elas, consulte Visão geral das amostras de instrumentação.
Implante o coletor criado pelo Google ou o coletor do OpenTelemetry e configure-o da seguinte maneira:
- Exporte dados de métricas com o exportador googlemanagedprometheus.
- Configure o processador k8sattributes para extrair metadados, como o namespace, do ambiente.
- Configure o processador transform/collision para definir os atributos project_id, location, cluster e namespace.
- Configure o processador transform/aco-gke para preencher os rótulos top_level_controller_name e top_level_controller_type.
Por exemplo, consulte otlp-k8s-ingest/config/collector.yaml, que é o arquivo de configuração do coletor criado pelo Google. Para saber mais sobre esse coletor, consulte Implantar o coletor do OpenTelemetry criado pelo Google no GKE.
Registre as cargas de trabalho do aplicativo no App Hub.

Usar o Google Cloud Managed Service para Prometheus no GKE

Para que o Google Cloud Observability anexe rótulos de aplicativos aos dados de métricas gerados pelas cargas de trabalho do aplicativo executadas em clusters do Google Kubernetes Engine, faça o seguinte:

Use o Google Cloud Managed Service para Prometheus com coleta gerenciada.
Implante suas cargas de trabalho em um cluster do Google Kubernetes Engine com versão pelo menos 1.32.1-gke.1439000.
Registre as cargas de trabalho do aplicativo no App Hub.

O Google Cloud Managed Service para Prometheus descobre os valores dos rótulos do aplicativo usando metadados de descoberta de serviços e adiciona os rótulos top_level_controller_{name,type} ao targetLabels.metadata. Durante a ingestão de métricas, o Google Cloud Observability usa os rótulos top_level_controller_{name,type} e a API App Hub para identificar seu aplicativo do App Hub e adicionar os rótulos adequados aos dados de métricas.

Usar o Cloud Run

Para que o Google Cloud Observability anexe rótulos de aplicativos aos dados de métricas gerados pelas suas cargas de trabalho do Cloud Run, faça o seguinte:

Instrumente seu aplicativo usando o OpenTelemetry ou o arquivo secundário do Managed Service para Prometheus para o Cloud Run. Para informações sobre essas abordagens, consulte os seguintes documentos:
- Implantar o OpenTelemetry Collector criado pelo Google no Cloud Run
- Usar o arquivo secundário do Prometheus para o Cloud Run
Registre as cargas de trabalho do aplicativo no App Hub.

Verificar rótulos de métricas

Para verificar se o aplicativo está enviando métricas do Prometheus para seu projeto, faça o seguinte:

Verifique se o aplicativo está enviando métricas do Prometheus para o projeto:
1. No console Google Cloud , acesse a página do Metrics explorer:
  Acesse o Metrics Explorer
  
  Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.
2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta habilitada para apps.
3. No elemento Metric, expanda o menu Selecionar uma métrica, digite Prometheus Target na barra de filtro e use os submenus para selecionar um tipo de recurso e métrica específicos:
  1. No menu Active resources, selecione Prometheus Target.
  2. Para selecionar uma métrica, use os menus Categorias de métricas ativas e Métricas ativas.
  3. Clique em Aplicar.
4. Para adicionar filtros que removem séries temporais dos resultados da consulta, use o elemento Filtro.
5. Configure a visualização dos dados.
  Para ver os rótulos, expanda o menu Filtro. Cada entrada no Filtro corresponde a um rótulo.
  
  Para mais informações sobre como configurar um gráfico, consulte Selecionar métricas ao usar o Metrics Explorer.
Se você não estiver vendo nenhuma métrica do Prometheus, revise sua configuração.

Se as métricas do Prometheus não contiverem rótulos de aplicativo, faça o seguinte:

Verifique se você registrou sua carga de trabalho ou serviço no App Hub.
Examine os registros para determinar se há erros.

Por exemplo, se você implantar um coletor do OpenTelemetry ou o coletor criado pelo Google e estiver executando no Google Kubernetes Engine, faça o seguinte:
1. No console Google Cloud , acesse a página Cargas de trabalho:
  Acesse Cargas de trabalho
  
  Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Kubernetes Engine.
2. Selecione a implantação do coletor e, em seguida, a guia Registros.
Se você estiver usando um Coletor do OpenTelemetry ou o Coletor criado pelo Google, revise a configuração dele. O coletor precisa fazer o seguinte:
- Exporte dados de métricas com o exportador googlemanagedprometheus.
- Configure o processador k8sattributes para extrair metadados, como o namespace, do ambiente.
- Configure o processador transform/collision para definir os atributos project_id, location, cluster e namespace.
- Configure o processador transform/aco-gke para preencher os rótulos top_level_controller_name e top_level_controller_type.
Para um exemplo, consulte o arquivo de configuração do coletor criado pelo Google: otlp-k8s-ingest/config/collector.yaml.

Adicionar atributos de aplicativo a períodos de rastreamento

Você não instrumenta seu aplicativo para que atributos específicos dele sejam anexados aos intervalos enviados ao projeto do Google Cloud . Em vez disso, a Observabilidade do Google Cloud usa atributos de recursos do OpenTelemetry e a API App Hub para identificar o aplicativo do App Hub associado a um intervalo. Em seguida, ela adiciona os atributos específicos do aplicativo antes de armazenar o intervalo.

Para que o Google Cloud Observability anexe atributos de recursos específicos do aplicativo aos dados de rastreamento gerados pelos serviços e cargas de trabalho do aplicativo, faça o seguinte:

Instrumente seu aplicativo com o OpenTelemetry e configure o exportador para enviar dados de rastreamento ao endpoint da API Telemetry (OTLP).

Recomendamos uma exportação baseada em coletor. Os documentos a seguir descrevem coletores que anexam todos os atributos necessários aos dados de extensão:
Se você não usar um dos coletores anteriores, configure sua instrumentação ou coletor para anexar todos os atributos obrigatórios.
Implante seus serviços e cargas de trabalho na infraestrutura compatível.
Registre seus serviços e cargas de trabalho no App Hub.

Para mais informações sobre esses atributos, consulte Convenções semânticas doGoogle Cloud App Hub.

Atributos obrigatórios

Esta seção se aplica a configurações em que você não usa um dos coletores recomendados. Por exemplo, talvez você queira escrever seu próprio coletor ou prefira exportar diretamente os dados de rastreamento.

Atributos que identificam seu projeto e o local do recurso

Defina os seguintes atributos:

Defina cloud.provider como "gcp".
cloud.account.id: defina como o ID do projeto.
cloud.availability_zone ou cloud.region: defina como a zona ou região em que seus recursos estão localizados. É possível definir os dois atributos.

Os detectores de recursos podem ajudar você a definir os atributos anteriores:

Atributos para cargas de trabalho do Google Kubernetes Engine

Para uma carga de trabalho do Google Kubernetes Engine, configure seu coletor ou instrumentação para fazer o seguinte:

Extraia metadados, como o namespace, do ambiente.
Extraia os metadados relevantes do processador k8sattributes.
Defina os atributos project_id, location, cluster e namespace.
Defina os rótulos top_level_controller_name e top_level_controller_type.

Para um exemplo baseado em coletor, consulte otlp-k8s-ingest/config/collector.yaml. Esse coletor usa o processador k8sattributesprocessor.

Atributos para cargas de trabalho de VM

Se você implantar o aplicativo em uma VM, ela precisará ser associada a um grupo gerenciado de instâncias (MIG). Você também precisa anexar os seguintes atributos:

gcp.gce.instance_group_manager.name
gcp.gce.instance_group_manager.region ou gcp.gce.instance_group_manager.zone