Usar exemplares do Prometheus

Neste documento, descrevemos como usar o Google Cloud Managed Service para Prometheus para ingerir exemplares do Prometheus em métricas de histograma. Use uma das seguintes opções:

  • Coleta gerenciada do Managed Service para Prometheus versão 0.7.0 ou superior
  • Coleta gerenciada e autoimplantada do Managed Service para Prometheus versão 2.35.0-gmp.5-gke.0 ou superior
  • O OpenTelemetry Collector

Os exemplares normalmente são usados para associar identificadores de trace a dados de métrica coletados em um intervalo de tempo, mas podem ser usados para associar dados de não métrica às métricas coletadas. Armazenar informações de trace com os dados de métrica permite identificar rapidamente os traces associados a uma alteração repentina nos valores de métrica. Você não precisa comparar manualmente as informações de trace e os dados de métrica usando os carimbos de data/hora para identificar o que estava acontecendo no aplicativo quando os dados de métrica foram registrados.

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

A captura de tela a seguir mostra um gráfico do Grafana com conjuntos de buckets de histograma e exemplares associados, com um exemplar expandido:

Gráfico do Grafana mostrando buckets de histograma e exemplares.

Exemplares do Prometheus no Managed Service para Prometheus

Os exemplares são aceitos no Prometheus usando o formato de exposição do OpenMetrics (em inglês). Um exemplar do OpenMetrics tem a seguinte estrutura:

  • O valor do exemplar: precisa ser um número inteiro ou um ponto flutuante de 64 bits.
  • (Opcional) Um carimbo de data/hora: precisa ser segundos da época do Unix. Pode ser negativo.
  • Inúmeros rótulos para o exemplar, normalmente incluindo valores trace_id e span_id. O comprimento total de todos os nomes e valores de rótulos não pode exceder 128 caracteres UTF-8 ou 128 runas em aplicativos Go.

O Google Cloud Managed Service para Prometheus só pode ingerir exemplares anexados a métricas de histograma. Não é possível ingerir exemplares 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 é compatível com exemplares. As métricas de não distribuição no Cloud Monitoring não são compatíveis com exemplares.

Os exemplares permanecem disponíveis para consulta por 24 meses. Compare esse período de armazenamento com o Prometheus upstream, em que os exemplares ficarão retidos apenas enquanto os dados estiverem na memória, normalmente menos de 14 dias. O Managed Service para Prometheus armazena exemplares com a série temporal. Por isso, os exemplares ficam retidos de acordo com a política de retenção da série temporal. Para mais informações sobre a retenção de dados no Cloud Monitoring, consulte este link.

Ativar ingestão de exemplares

Se você estiver usando o Managed Service para Prometheus com a coleta gerenciada versão 0.7.0 ou superior, a ingestão de exemplares será ativada automaticamente.

Se você estiver usando o Managed Service para Prometheus com coleta autoimplantada, será preciso ativar a ingestão de exemplares ao iniciar o servidor especificando a seguinte flag de recurso:

--enable-feature=exemplar-storage

Gravar métricas com exemplares

Cada cliente do Prometheus tem as próprias instruções para usar corretamente os exemplares nesse cliente. Siga estas instruções para que seu aplicativo exponha métricas no formato do OpenMetrics para o Prometheus fazer a raspagem de dados do endpoint /metrics do aplicativo. Veja exemplos:

Integrar com o Cloud Trace

É possível gravar histogramas do Prometheus com exemplares compatíveis com o Cloud Trace. É possível exibir os dados, incluindo os exemplares, em um gráfico de mapa de calor do Cloud Monitoring, em que é possível usar os exemplares para visualizar detalhes sobre os períodos de trace relacionados. Também é possível analisar os dados de trace no Trace. Para mais informações, consulte Mostrar exemplares em um gráfico de mapa de calor e Visualizar detalhes do trace.

Para criar exemplares compatíveis com o Trace, os exemplares do Prometheus precisam conter os seguintes rótulos:

  • project_id
  • trace_id
  • span_id

Se seu exemplar tiver esses três rótulos, eles serão usados para criar um objeto SpanContext compatível com o Trace anexado ao exemplar criado para o bucket Distribution do Cloud Monitoring.

Todos os rótulos, exceto os que compõem um SpanContext completo, são adicionados a um objeto DroppedLabels anexado ao exemplar de um bucket Distribution.

Consultar métricas com exemplares

A API Prometheus expõe o endpoint api/v1/query_exemplars para consultar exemplares.

As interfaces de consulta configuradas para interagir com o Google Cloud Managed Service para Prometheus incluem automaticamente consultas de exemplares. Para informações sobre como configurar interfaces de consulta, acesse Consultar usando Grafana ou Consultar usando a API ou IU do Prometheus.