Use exemplares do Prometheus

Este documento descreve como pode usar o serviço gerido do Google Cloud para o Prometheus para carregar exemplos do Prometheus em métricas de histogramas. Tem de usar um dos seguintes elementos:

  • Versão 0.7.0 ou superior da recolha gerida do Managed Service for Prometheus
  • Versão de recolha implementada automaticamente do Managed Service for Prometheus 2.35.0-gmp.5-gke.0 ou superior
  • O OpenTelemetry Collector

Normalmente, os exemplos são usados para associar identificadores de rastreio a dados de métricas recolhidos num intervalo de tempo, mas podem ser usados para associar quaisquer dados não métricos às métricas recolhidas. O armazenamento de informações de rastreio com os dados das métricas permite-lhe identificar rapidamente os rastreios associados a uma alteração súbita nos valores das métricas. Não tem de fazer referências cruzadas manualmente às informações de rastreio e aos dados das métricas através de datas/horas para identificar o que estava a acontecer na aplicação quando os dados das métricas foram registados.

Os exemplos do serviço gerido para Prometheus são compatíveis com o Cloud Trace e com ferramentas de rastreio de terceiros, como o Grafana Tempo.

A captura de ecrã seguinte mostra um gráfico do Grafana de conjuntos de contentores de histogramas e exemplares associados, com um exemplar expandido:

Gráfico do Grafana a mostrar contentores de histogramas e exemplares.

Exemplares do Prometheus no Managed Service for Prometheus

Os exemplares são suportados no Prometheus através do formato de exposição OpenMetrics. Um exemplar OpenMetrics tem a seguinte estrutura:

  • O valor do exemplo tem de ser um número inteiro ou um flutuante de 64 bits.
  • (Opcional) Uma indicação de tempo: tem de ser segundos da época Unix e pode ser negativa.
  • Um número de etiquetas para o exemplar, normalmente incluindo valores trace_id e span_id; o comprimento total de todos os nomes e valores das etiquetas não pode exceder 128 carateres UTF-8 ou 128 runes em aplicações Go.

O serviço gerido do Google Cloud para Prometheus só pode carregar exemplos anexados a métricas de histogramas. Não é possível carregar exemplos anexados a métricas de contador. As métricas de histograma do Prometheus são convertidas no tipo análogo do Cloud Monitoring Distribution, que suporta exemplos. As métricas de não distribuição no Cloud Monitoring não suportam exemplares.

Os exemplos permanecem disponíveis para consulta durante 24 meses. Compare este período de retenção com o Prometheus a montante, onde os exemplares são retidos apenas enquanto os dados estão na memória, normalmente, menos de 14 dias. O Managed Service for Prometheus armazena exemplares com as séries cronológicas, pelo que os exemplares são retidos de acordo com a política de retenção das séries cronológicas. Para mais informações acerca da retenção de dados no Cloud Monitoring, consulte o artigo Retenção de dados.

Ative o carregamento de exemplos

Se estiver a usar o Managed Service for Prometheus com a versão 0.7.0 ou superior da recolha gerida, o carregamento de exemplos é ativado automaticamente.

Se estiver a usar o Managed Service for Prometheus com a recolha implementada automaticamente, tem de ativar a carregamento de exemplos quando iniciar o servidor especificando a seguinte flag de funcionalidade:

--enable-feature=exemplar-storage

Escreva métricas com exemplares

Cada cliente do Prometheus tem as suas próprias instruções para usar corretamente os exemplares nesse cliente. Siga estas instruções para que a sua aplicação exponha métricas no formato OpenMetrics para o Prometheus extrair dados do ponto final /metrics da aplicação. Para ver exemplos, consulte o seguinte:

Faça a integração com o Cloud Trace

Pode escrever histogramas do Prometheus com exemplos compatíveis com o Cloud Trace. Pode apresentar os dados, incluindo os exemplos, num gráfico de mapa térmico do Cloud Monitoring, onde pode usar os exemplos para ver detalhes sobre os intervalos de rastreio relacionados. Também pode analisar os dados de rastreio no Trace. Para mais informações, consulte o artigo Mostre exemplos num gráfico de mapa térmico.

Para criar exemplos compatíveis com o rastreio, os seus exemplos do Prometheus têm de conter as seguintes etiquetas:

  • project_id
  • trace_id
  • span_id

Se o seu exemplar incluir estas três etiquetas, as etiquetas são usadas para criar um objeto SpanContext compatível com o Trace que é anexado ao exemplar criado para o contentor Distribution do Cloud Monitoring.

Todas as etiquetas que não sejam as que compõem um SpanContext são adicionadas a um objeto DroppedLabels anexado ao exemplo de um grupo Distribution.

Consulte métricas com exemplos

A API Prometheus expõe o ponto final api/v1/query_exemplars para consultar exemplos.

As interfaces de consulta configuradas para interagir com o serviço gerido do Google Cloud para Prometheus incluem automaticamente a consulta de exemplares. Para obter informações sobre a configuração de interfaces de consulta, consulte os artigos Consultar com o Grafana ou Consultar com a API ou a IU do Prometheus.