Acessar a telemetria de aplicativo

Este documento descreve como visualizar os painéis prontos para uso (OOTB, na sigla em inglês) dos aplicativos, serviços e cargas de trabalho do App Hub. Esses painéis ajudam a entender o desempenho dos recursos do aplicativo e a diagnosticar problemas.

A telemetria exibida nesses painéis prontos para uso inclui dados de registros e métricas, além de informações sobre incidentes abertos. Os painéis de aplicativos fornecem informações como local, importância e proprietários. Os painéis de serviços e cargas de trabalho incluem informações sobre o App Hub e os tipos de infraestrutura.

Para ver dados de rastreamento, use o Explorador de rastreamento. Para mais informações, consulte a seção Analisar dados de rastreamento deste documento.

Rótulos específicos do aplicativo

Esta seção lista os rótulos e atributos específicos do App Hub que podem ser anexados aos seus dados de registro, métricas e rastreamento. Esses rótulos permitem que o Google Cloud Observability crie a hierarquia de painéis prontos para uso e filtre a telemetria mostrada para um serviço ou carga de trabalho. Também é possível usar esses rótulos para filtrar seus dados de registro, métrica e rastreamento.

Rótulos ou atributos específicos do aplicativo são anexados a dados de registro, métricas e rastreamento quando o aplicativo registrado é executado na infraestrutura compatível com o Application Monitoring. Os dados de métricas do Prometheus também incluem rótulos de aplicativos para algumas configurações do Google Cloud Managed Service para Prometheus.

Rótulos de registro

As entradas de registro contêm um campo apphub que lista os rótulos do aplicativo e de um serviço ou carga de trabalho. Confira a seguir o formato desses dados:

apphub: {
  application: {
    id: "my-app"
    location: "my-app-location"
  }
  workload: {
    criticalityType: "MEDIUM"
    environmentType: "STAGING"
    id: "my-workload-id"
  }
}

Rótulos de métrica

Esta seção descreve quando os rótulos específicos do aplicativo são anexados aos dados de métricas gerados por recursos do Google Cloud e às métricas do Prometheus ingeridas usando o Google Cloud Managed Service para Prometheus. A seguir, interprete a.b.{x,y} como a.b.x e a.b.y.

Os seguintes rótulos de aplicativos do App Hub são anexados aos dados de métricas dos recursos Google Cloud usados pelo aplicativo:

  • metadata.system_labels.apphub_application_{container,id,location}
  • metadata.system_labels.apphub_{workload,service}_{criticality_type,environment_type,id}

Os rótulos de aplicativos do App Hub são anexados às métricas do Google Cloud Managed Service para Prometheus quando uma das seguintes condições é verdadeira:

  • Uma carga de trabalho está sendo executada em um cluster do Google Kubernetes Engine com a versão 1.30 ou mais recente, e o tipo de controlador da carga de trabalho é um dos seguintes:

    • apps.k8s.io/{Deployment,StatefulSet,DaemonSet}
    • batch.k8s.io/CronJob

  • Ao usar o OpenTelemetry no Cloud Run.

  • Ao usar o OpenTelemetry no Google Kubernetes Engine e seguir as orientações de ingestão do OTLP no Kubernetes.

O serviço gerenciado para Prometheus usa a API App Hub para determinar se um aplicativo do App Hub existe. Quando um aplicativo é encontrado, os seguintes rótulos específicos do aplicativo são adicionados aos dados de rastreamento:

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

Atributos de recursos de rastreamento

Os seguintes atributos de recursos específicos do aplicativo podem ser anexados a dados de rastreamento:

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

Os atributos de recursos específicos do aplicativo são anexados aos dados de rastreamento quando as seguintes condições são verdadeiras:

  • Seus aplicativos do App Hub usam recursos Google Cloud compatíveis.
  • Você instrumenta um aplicativo com o OpenTelemetry e envia os dados de rastreamento coletados do seu aplicativo para o projeto usando o endpointGoogle Cloud OTLP.
  • Os dados enviados ao seu projeto incluem atributos de recursos do OpenTelemetry que identificam os recursos Google Cloud compatíveis usados pelo seu aplicativo. Os atributos precisam incluir o seguinte:
    • 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 o k8s.cluster.name, o k8s.namespace e o tipo de implantação do Kubernetes definidos.

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

    Quando você instrumenta um aplicativo, o Google Cloud Observability usa os atributos de recurso anteriores e a API App Hub para identificar seu aplicativo do App Hub. Os rótulos 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 do App HubGoogle Cloud .

Rótulos de políticas de alertas

Os rótulos de serviço e carga de trabalho não são anexados automaticamente às políticas de alerta. No entanto, é possível associar uma política de alertas a uma carga de trabalho ou serviço específico anexando todos os rótulos a seguir com as seguintes chaves à política de alertas:

  • apphub_application_location
  • apphub_application_id
  • apphub_service_id ou apphub_workload_id

Quando uma política de alertas inclui as chaves anteriores, os incidentes relacionados a ela são mostrados nos painéis prontos para uso.

Para mais informações, consulte Associar uma política de alertas a um serviço ou uma carga de trabalho.

O console Google Cloud redefine automaticamente o seletor de recursos de uma pasta ativada para apps para o projeto de gerenciamento da pasta quando uma página do Google Cloud Observability é aberta.

O Cloud Logging é compatível com pastas como um recurso. Por exemplo, é possível criar gravadores e buckets de registros em um recurso de pasta. Da mesma forma, as pastas contêm buckets de registros _Default e _Required, e talvez você queira ver o conteúdo deles. Para acessar o recurso de pasta, use o seletor de recursos e selecione manualmente a pasta habilitada para apps.

Antes de começar

Antes de usar o Application Monitoring, configure o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado. Esse é o projeto que você usa para ver os dados de telemetria do aplicativo:

  • Para ter as permissões necessárias para ver dados de métricas e registros, criar políticas de alertas e personalizar painéis, peça ao administrador para conceder a você os seguintes papéis do IAM:

    • Leitor de registros (roles/logging.viewer) no projeto host do App Hub ou no projeto de gerenciamento da pasta ativada para apps e em qualquer outro projeto listado no escopo de registros padrão. Essa função concede acesso à maioria das entradas de registro no bucket de registros _Default. Para mais informações, consulte Papéis do Logging.
    • Acessador da visualização de registros (roles/logging.viewAccessor) nas visualizações de registros listadas no escopo de registros padrão do projeto host do App Hub ou no projeto de gerenciamento da sua pasta habilitada para gerenciar apps. Para saber mais sobre como conceder acesso a uma visualização de registro, consulte Controlar o acesso a uma visualização de registro.
    • Editor do Monitoring (roles/monitoring.editor) no projeto de host do App Hub ou no projeto de gerenciamento da pasta ativada para apps. Para principais que não precisam criar ou modificar políticas de alertas ou painéis, considere conceder o papel Leitor do Monitoring (roles/monitoring.viewer).
    • Usuário do Cloud Trace (roles/cloudtrace.user) no projeto host do App Hub ou no projeto de gerenciamento da pasta ativada para apps e nos projetos no escopo de rastreamento padrão.
    • Leitor do App Hub (roles/apphub.viewer) no projeto host do App Hub ou no projeto de gerenciamento da pasta ativada para apps. Para mais informações, consulte Papéis e permissões do App Hub.

    Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

    Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

  • Verifique se você configurou o escopo de capacidade de observação do projeto host do App Hub ou o projeto de gerenciamento da sua pasta habilitada para gerenciar apps. Para mais informações, consulte Configurar o Application Monitoring.

    O escopo de observabilidade controla quais dados estão disponíveis para o projeto host do App Hub ou para o projeto de gerenciamento da sua pasta habilitada para gerenciar apps. As configurações padrão desses escopos podem não permitir que você veja todos os dados de métricas ou registros.

  • Atualize as políticas de alertas que monitoram os dados do aplicativo para incluir rótulos específicos do aplicativo. Para mais informações, consulte Associar uma política de alertas a um serviço ou uma carga de trabalho.

Ver o resumo de todos os aplicativos

O painel OOTB de nível superior oferece um resumo conciso do estado dos seus aplicativos registrados. Para cada aplicativo, essa página lista o número de incidentes abertos e informações sobre o local, a gravidade e o ambiente.

Para abrir o painel OOTB de nível superior, que lista informações de resumo dos aplicativos registrados no App Hub, faça o seguinte:

  1. No console Google Cloud , acesse a página Monitoramento de aplicativos:

    Acessar Monitoramento de aplicativos

    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 o projeto host do App Hub ou o projeto de gerenciamento da pasta habilitada para apps.

  3. Opcional: para abrir um aplicativo no App Hub, clique em Mais e selecione Gerenciar no App Hub.

  4. Para abrir o painel OOTB de um aplicativo, selecione-o. A próxima seção fornece orientações sobre como analisar ou interpretar a telemetria.

Analise a telemetria e os incidentes do aplicativo

Quando você seleciona um aplicativo listado na página Monitoramento de aplicativos, o painel OOTB de nível superior do aplicativo é aberto. Esse painel ajuda você a entender a integridade do seu aplicativo, resumindo o número de incidentes abertos e listando valores para vários indicadores de ouro. Por exemplo, se essa página mostrar falhas generalizadas, isso pode indicar que a origem da falha é a infraestrutura e não o aplicativo.

Para abrir um painel OOTB de um aplicativo, faça o seguinte:

  1. No console Google Cloud , acesse a página Monitoramento de aplicativos:

    Acessar Monitoramento de aplicativos

    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 o projeto host do App Hub ou o projeto de gerenciamento da pasta habilitada para apps.

  3. Na página Monitoramento de aplicativos, selecione o nome de um aplicativo.

    O painel OOTB do aplicativo é aberto com a guia Visão geral selecionada. Essa guia lista cada serviço e carga de trabalho, além do número de incidentes abertos e valores dos indicadores de ouro:

    • Tráfego: taxas de solicitações recebidas no serviço ou na carga de trabalho durante o período selecionado.
    • Taxa de erros do servidor: porcentagem média de solicitações recebidas que geram ou mapeiam códigos de resposta HTTP 5xx durante o período selecionado.
    • Latência P95: 95º percentil de latência de uma solicitação atendida no período selecionado, em milissegundos.
    • Saturação: mede o nível de ocupação do serviço ou da carga de trabalho. Por exemplo, para grupos de instâncias gerenciadas (MIGs), implantações do Cloud Run e do Google Kubernetes Engine, esse campo mostra a utilização da CPU.

    Na guia Visão geral, você pode fazer o seguinte:

    • Redefina o período. Quando você abre o painel, o período é definido como a hora mais recente.
    • Veja informações sobre o aplicativo, como operador, desenvolvedor e proprietários de empresas.
    • Abra o aplicativo, o serviço ou a carga de trabalho no App Hub.
    • Abra o painel de um serviço ou carga de trabalho.

  4. Para conferir a telemetria do aplicativo e informações sobre incidentes em aberto, selecione a guia Painel.

    A guia Painel mostra informações de registros, métricas e incidentes. A guia é configurada para sobrepor anotações de eventos nos gráficos. Elas ajudam a correlacionar dados de diferentes fontes ao resolver um problema. Para ver quais anotações estão ativadas, clique em Anotações na barra de ferramentas.

    A guia também contém filtros que podem ser usados para restringir os dados exibidos. Para mais informações sobre como analisar os dados mostrados nesta guia, consulte as seguintes seções deste documento:

Filtrar um painel

A guia Painel mostra dados de serviços e cargas de trabalho em um aplicativo. No entanto, é possível filtrar esse painel para um serviço específico ou um conjunto de serviços.

Por exemplo, a barra de ferramentas na guia Painel contém um filtro como apphub_service_id: *. Se quiser ver dados de serviços específicos, clique em Menu e selecione os serviços na lista.

Analisar dados de registros

Se você estiver na guia Painel de um painel de aplicativos, os dados de registro vão aparecer na seção Registros de aplicativos. Caso contrário, os dados vão aparecer na seção Registros.

As seções Registros de aplicativos e Registros de um painel mostram entradas de registro que correspondem a um filtro e são armazenadas pelos recursos listados no escopo de registro padrão do projeto host do App Hub ou do projeto de gerenciamento da pasta ativada por apps. Para aplicativos, o filtro é semelhante a este:

-- Application logs
(apphub_application_location=global)
(apphub_application_id=my-app)

Para serviços e cargas de trabalho, o filtro contém cláusulas adicionais. Para conferir o filtro aplicado aos dados de registro, clique em Mostrar consulta.

Se você quiser escrever consultas, abra um menu flutuante ou a página Explorador de registros. As duas opções permitem escrever e executar consultas, além de mudar o escopo. No entanto, o painel flutuante retém seu contexto atual e permite salvar os resultados da análise detalhada em um painel personalizado:

  • Para abrir um menu suspenso, clique em Analisar dados.

    Quando a análise detalhada estiver concluída, clique em Cancelar para fechar o menu flutuante e descartar as mudanças. Se quiser salvar as mudanças em um painel personalizado, clique em Salvar no painel e preencha a caixa de diálogo. Não é possível salvar as mudanças no painel que você estava visualizando ao abrir o submenu.

    O menu suspenso não lista os filtros mostrados pelo botão Mostrar consulta. Esses filtros são aplicados no nível do painel e não podem ser removidos.

  • Para abrir a página do Explorador de registros em uma nova guia do navegador, clique em Ver no Explorador de registros.

    A consulta é pré-configurada para mostrar entradas de registro que correspondem a rótulos de aplicativos específicos e que estão no período especificado pelo painel. Quando você fecha a guia do navegador, as mudanças são descartadas.

Para mais informações sobre como explorar seus registros, consulte os seguintes documentos:

Acessar dados de métricas

Os gráficos e tabelas no painel mostram indicadores de ouro e outros dados de métricas relevantes para os recursos usados pelo seu aplicativo, serviço ou carga de trabalho. Os dados exibidos podem ser armazenados em qualquer projeto listado pelo escopo de métricas do projeto host do App Hub ou do projeto de gerenciamento da pasta com app ativado.

Em qualquer gráfico ou tabela que mostre dados de métricas, é possível conferir detalhes como o tipo de métrica e as opções de agregação. Para ver essas informações, acesse a barra de ferramentas de um gráfico ou tabela e clique em Informações.

Para analisar um gráfico ou uma tabela com mais detalhes, abra um submenu ou a página Metrics Explorer. Com as duas opções, você pode testar diferentes configurações de gráfico e salvar os resultados em um painel personalizado. No entanto, o painel flutuante mantém seu contexto atual:

  • Para abrir um menu suspenso, clique em Analisar dados.

    Quando a análise detalhada estiver concluída, clique em Cancelar para fechar o menu flutuante e descartar as mudanças. Se quiser salvar as mudanças em um painel personalizado, clique em Salvar no painel e preencha a caixa de diálogo. Não é possível salvar as mudanças no painel que você estava visualizando ao abrir o submenu.

  • Para ver o gráfico ou a tabela no Metrics Explorer, acesse a barra de ferramentas, clique em Mais e selecione Ver no Metrics Explorer.

    Agora você tem um gráfico temporário que pode ser modificado e analisado. Por exemplo, você pode mudar as opções de agregação ou o estilo de exibição. Para salvar o gráfico em um painel personalizado, clique em Salvar no painel e preencha o

Analisar incidentes

A seção Incidentes dos painéis lista os incidentes recentes das políticas de alertas associadas a um serviço ou carga de trabalho. Essas políticas de alerta precisam ser armazenadas no projeto host do App Hub ou no projeto de gerenciamento da pasta ativada para apps.

Se não houver entradas na seção Incidentes, isso significa que você não tem políticas de alerta associadas a um serviço ou uma carga de trabalho. Para criar essa associação, adicione rótulos à política. Para mais informações, consulte Associar uma política de alertas a um serviço ou uma carga de trabalho.

Para mais informações sobre seus incidentes e políticas de alertas, faça o seguinte:

  • Para encontrar detalhes sobre a política de alertas que causou o incidente, clique no nome dela. O painel que é aberto mostra informações detalhadas sobre a política de alertas, incluindo um gráfico com os dados monitorados e os rótulos.

  • Para conferir todas as políticas de alerta associadas ao aplicativo, acesse a barra de ferramentas e clique em Dados do Explorer. Um menu suspenso será aberto com todas as políticas. Para voltar ao painel, clique em Cancelar.

Analisar dados de trace

Os painéis OOTB não mostram dados de rastreamento. No entanto, é possível conferir os dados de trace de um aplicativo, serviço ou carga de trabalho usando a página Trace Explorer. Quando você abre essa página, os dados de trace armazenados nos projetos listados pelo escopo de trace padrão são recuperados do armazenamento. Os dados mostrados dependem dos seus papéis do IAM nesses projetos, da configuração de período e dos filtros aplicados. Para saber quando os dados de rastreamento contêm atributos de aplicativo, consulte Atributos de recursos de rastreamento.

Para conferir os dados de rastreamento do aplicativo, faça o seguinte:

  1. No console Google Cloud , acesse a página Explorador de traces:

    Acessar o Explorador de traces

    Também é possível encontrar essa página usando a barra de pesquisa.

  2. Na barra de ferramentas do console Google Cloud , selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta habilitada para apps.

  3. Aplique filtros para restringir os dados de rastreamento:

    • Para filtrar por aplicativo, use o filtro de período Aplicativo do App Hub.
    • Para filtrar por serviço, use o filtro de período Serviço do App Hub.
    • Para filtrar por carga de trabalho, use o filtro de período Carga de trabalho do App Hub.
    • Para adicionar um filtro personalizado, na barra de ferramentas, selecione Adicionar filtro, Adicionar filtro de atributo e preencha a caixa de diálogo. A sintaxe do campo Key precisa corresponder à sintaxe da chave de um atributo em um intervalo. Por exemplo, para filtrar pelo identificador do host, insira host.id.

    Para informações sobre como usar a interface de trace, consulte Encontrar e explorar traces.

Analisar a telemetria e os incidentes de serviços ou cargas de trabalho

Um painel OOTB é fornecido para cada serviço e carga de trabalho. Esses painéis mostram informações de registros, métricas e incidentes, e podem ajudar você a entender a integridade de um serviço ou uma carga de trabalho específica. É possível analisar os dados nesses painéis prontos para uso da mesma forma que os dados mostrados na guia Painel de um aplicativo.

Para abrir o painel OOTB de um serviço ou carga de trabalho, faça o seguinte:

  1. No console Google Cloud , acesse a página Monitoramento de aplicativos:

    Acessar Monitoramento de aplicativos

    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 o projeto host do App Hub ou o projeto de gerenciamento da pasta habilitada para apps.

  3. Na página Monitoramento de aplicativos, selecione o nome de um aplicativo e depois um serviço ou uma carga de trabalho.

    Um painel mostra as informações de registro, métrica e incidente do serviço ou da carga de trabalho selecionada. Para cargas de trabalho, o painel é configurado para sobrepor anotações de eventos nos gráficos. As anotações podem ajudar você a correlacionar dados de diferentes fontes ao resolver um problema. Para ver quais anotações estão ativadas, clique em Anotações na barra de ferramentas.

    O card de resumo mostra informações gerais e o tipo de infraestrutura. Quando o tipo de infraestrutura não pode ser identificado, esse campo mostra um texto genérico, como Serviço do App Hub. Para mais informações, consulte Infraestrutura compatível com o Application Monitoring.

    Para informações sobre como analisar os dados em um painel de serviços ou de carga de trabalho, consulte as seguintes seções deste documento:

Criar um painel personalizado

O Google Cloud Observability permite criar painéis personalizados, que oferecem controle total sobre o conteúdo. Os painéis personalizados são listados na página Painéis do console do Google Cloud e podem ser copiados, editados e excluídos. Eles também podem ser o destino em que você salva um widget de painel configurado. Por exemplo, se você estiver analisando um gráfico em um painel de aplicativos, poderá salvá-lo em um painel personalizado. Para isso, acesse a barra de ferramentas e selecione Salvar no painel.

Se você planeja criar um painel personalizado para um aplicativo, serviço ou carga de trabalho, o seguinte pode ser útil:

Associar uma política de alertas a um aplicativo do App Hub

Para associar uma política de alertas a um serviço ou carga de trabalho, adicione rótulos específicos do aplicativo a ela. Quando você adiciona esses rótulos, eles são listados na política de alertas e também incluídos em todos os incidentes. Para saber mais sobre rótulos, consulte Classificar incidentes com rótulos.

Para associar uma política de alertas a uma carga de trabalho ou serviço usando o console Google Cloud , faça o seguinte:

  1. No console Google Cloud , acesse a página  Alertas:

    Acessar Alertas

    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 consoleGoogle Cloud , selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta habilitada para apps.
  3. Encontre a política de alertas, clique em Ver mais, selecione Editar e acesse a seção Notificações e nome.
  4. Na seção Marcadores de aplicativo, selecione seu aplicativo e depois selecione sua carga de trabalho ou serviço.
  5. Clique em Salvar política.

Depois de concluir essas etapas, os rótulos com as seguintes chaves serão anexados à sua política de alertas. Esses rótulos identificam seu aplicativo e seu serviço ou carga de trabalho:

  • apphub_application_location
  • apphub_application_id
  • apphub_service_id ou apphub_workload_id

Também é possível adicionar identificadores definidos pelo usuário a uma política de alertas usando a Google Cloud CLI, o Terraform ou a API Cloud Monitoring. No entanto, você precisa usar as chaves de rótulo mostradas no exemplo anterior. Para ver mais informações, consulte os seguintes tópicos:

Resolver problemas

Para informações que podem ajudar você a entender quais dados estão sendo mostrados ou por que um painel não exibe dados, consulte Solucionar problemas do Application Monitoring.