Correlacionar métricas e traces usando exemplos

É possível usar exemplares para correlacionar dados de métricas e traces. Um exemplar é uma solicitação ou um período de amostra representativo associado a uma medição de métrica. O aplicativo pode criar e anexar exemplares a dados de métricas. Como alternativa, o Google Cloud Observability pode gerá-los dinamicamente ao criar gráficos de resultados de consultas. Ao vincular um ID de trace individual a uma métrica agregada, os exemplares ajudam a investigar rapidamente a causa raiz de picos de latência ou erros.

Este documento descreve como configurar OpenTelemetry para criar e anexar exemplares de trace aos dados de métricas.

Se você criar um gráfico dos resultados da consulta SQL em um painel, o Google Cloud Observability também poderá gerar exemplares automaticamente. Para mais informações, consulte Gerar e mostrar exemplares de trace.

Sobre os exemplares

Os exemplares são uma maneira de associar dados arbitrários a dados de métricas. É possível usá-los para anexar dados de não métricas a medições. Um uso de exemplares é associar dados de trace a dados de métricas. No Cloud Monitoring, os exemplares podem ser anexados a dados de métricas que têm o Distribution tipo de valor. As métricas com valor de distribuição coletam muitas medições e as agrupam em buckets. Cada "ponto" é um histograma, que é uma matriz que lista as contagens de buckets. As medições reais não são mantidas, apenas as contagens de buckets. Para mais informações, consulte Sobre métricas com valor de distribuição.

Quando um ponto de dados de métrica é gravado, uma matriz de Exemplar objetos pode ser anexada a esses dados. Os exemplares, quando usados, anexam informações úteis aos dados de métricas. Por exemplo, quando o OpenTelemetry grava um exemplar, ele anexa um link ao intervalo atual de um trace.

Os dados do histograma normalmente são exibidos usando um mapa de calor. Quando um "ponto" contém um exemplar, o Cloud Monitoring anota o mapa de calor com um ponto:

  • Para conferir informações de resumo sobre o ponto de métrica, ative a dica de ferramenta da anotação.
  • Para acessar o trace, selecione a anotação.

Por exemplo, a amostra de instrumentação do Go usa o OpenTelemetry para gravar dados de métricas, dados de trace e exemplares. A captura de tela a seguir mostra o valor da métrica prometheus/http_server_duration_milliseconds/histogram após várias execuções do aplicativo:

Exemplo de um mapa de calor mostrando vários exercícios.

A captura de tela anterior mostra vários exemplares. A dica de ferramenta de um exemplar é expandida e mostra a data, o nome do trace, os percentis e um valor de latência.

Quando a anotação é selecionada, o trace vinculado no exemplar é mostrado:

Exemplo dos detalhes de um trace para um exemplar.

Quando as informações mostradas não são suficientemente detalhadas, selecione Ver no trace, que abre a página Trace Explorer. Nessa página, é possível conferir atributos de trace e acessar links para entradas de registro.

Como ativar exemplares do OpenTelemetry

Como o exemplo anterior ilustra, é possível configurar o OpenTelemetry para gravar exemplares que vinculam o span atual de um trace a uma medição de métrica. No entanto, para que os exemplares sejam gravados, faça o seguinte:

  1. Configure a métrica do OpenTelemetry e os SDKs de trace.

  2. Para incluir exemplares na sua instrumentação personalizada, verifique se a métrica está registrada em um período e se você transmite o contexto do período com a medição da métrica.

    Por exemplo, a função computeSubrequests segue as orientações anteriores. A função subRequestsHistogram.Record é invocada após tracer.Start e antes de span.End, que é adiada. Observe também que o contexto, ctx, é transmitido de tracer.Start para a função Record:

    func computeSubrequests(r *http.Request, subRequests int) error {
	// Add custom span representing the work done for the subrequests
	ctx, span := tracer.Start(r.Context(), "subrequests")
	defer span.End()

	// Make specified number of http requests to the /single endpoint.
	for i := 0; i < subRequests; i++ {
		if err := callSingle(ctx); err != nil {
			return err
		}
	}
	// record number of sub-requests made
	subRequestsHistogram.Record(ctx, int64(subRequests))
	return nil
}

    Para mais informações sobre esse exemplo, consulte Adicionar rastreamentos e métricas personalizados ao seu aplicativo.

A seguir