Instrumentar um aplicativo para o monitoramento de aplicativos

Pré-lançamento

Este produto ou recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

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. Ele 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 rótulos específicos do aplicativo se referem a rótulos 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 das 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 recursos: 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 prontos para uso 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 que o Google Cloud Observability identifique o aplicativo do App Hub.

Usar o OpenTelemetry no Kubernetes

Observação: recomendamos que você use essa abordagem com o Coletor do OpenTelemetry criado pelo Google. Se você executar cargas de trabalho no Google Kubernetes Engine, essa abordagem exportará a métrica do servidor HTTP que o Application Monitoring usa para gerar valores para o nível de tráfego, a taxa de erros do servidor e a latência das solicitações HTTP.

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:

1. Instrumente o aplicativo com o OpenTelemetry.

   • Para informações gerais, consulte Instrumentação e observabilidade.
   • Para links para amostras em Go, Java, Node.js e Python, além de informações sobre elas, consulte Visão geral das amostras de instrumentação.

2. 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.

3. 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:

1. Use o Google Cloud Managed Service para Prometheus com coleta gerenciada.

2. Implante suas cargas de trabalho em um cluster do Google Kubernetes Engine com versão 1.32.1-gke.1439000 ou mais recente.

3. Registre as cargas de trabalho do aplicativo no App Hub.

O Google Cloud Managed Service para Prometheus descobre os valores dos rótulos de aplicativos 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:

1. 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

2. 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:

1. Verifique se o aplicativo está enviando métricas do Prometheus para o projeto:

   1. No console Google Cloud , acesse a página  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:

1. Verifique se você registrou sua carga de trabalho ou serviço no App Hub.

2. 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.

3. 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

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

1. Registre seus serviços e cargas de trabalho no App Hub.
2. Instrumente seu aplicativo com o OpenTelemetry e envie os dados de rastreamento coletados do aplicativo para o projeto usando o endpoint OTLPGoogle Cloud .

3. Configure o OpenTelemetry Collector ou o coletor criado pelo Google para que os dados de período exportados incluam os atributos de recurso do OpenTelemetry que identificam os recursos Google Cloud compatíveis usados pelo seu aplicativo. Os atributos de recurso precisam incluir:

   • cloud.account.id
   • Um de cloud.{availability_zone,region}
   • Atributos específicos de recursos. Por exemplo, para uma carga de trabalho do Kubernetes, os intervalos precisam ter k8s.cluster.name, k8s.namespace e o tipo de implantação do Kubernetes definidos.

   Use processadores para que o coletor anexe atributos específicos do recurso aos seus intervalos. Para saber mais, consulte resourcedetectionprocessor e k8sattributesprocessor.

   A Observabilidade do Google Cloud usa os atributos de recurso anteriores e a API do App Hub para identificar seu aplicativo do App Hub. Os atributos específicos do aplicativo são adicionados aos dados de rastreamento quando um aplicativo é identificado.

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