Correlacionar métricas e traces usando exemplos

Este documento descreve os exemplos, que são pontos de dados de exemplo anexados a um ponto de dados de métrica. Um uso de exemplares é armazenar um link para um rastreamento, o que permite correlacionar seus dados de métrica e rastreamento. Este documento também descreve como usar o OpenTelemetry para gerar exemplares.

Sobre os gabaritos

Os exemplares são uma maneira de associar dados arbitrários a dados de métricas. É possível usar para anexar dados não métricos a medições. Um uso dos exemplares é associar dados de rastreamento a dados de métrica. No Cloud Monitoring, os exemplares podem ser anexados a dados de métricas que têm o tipo de valor Distribution. 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 intervalos. Para mais informações, consulte Sobre métricas de valor de distribuição.

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

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 ver um resumo sobre o ponto de métrica, ative a dica da anotação.
  • Para acessar o rastreamento, selecione a anotação.

Por exemplo, a amostra de instrumentação do Go usa o OpenTelemetry para gravar dados de métricas, dados de rastreamento 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 rastreamento vinculado no exemplo é exibido:

Exemplo dos detalhes de um trace para um exemplar.

Quando as informações exibidas não forem detalhadas o suficiente, selecione Ver no Trace, que abre a página do Trace Explorer. Nessa página, você pode conferir atributos de rastreamento e acessar links para entradas de registro.

Como ativar exemplos do OpenTelemetry

Como ilustrado no exemplo anterior, é possível configurar o OpenTelemetry para gravar exemplares que vinculam o intervalo atual de um trace a uma medição de métrica. No entanto, para que os exemplos sejam escritos, você precisa fazer o seguinte:

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

  2. Para incluir exemplares na sua instrumentação personalizada, garanta que a métrica seja registrada dentro de um intervalo e que você transmita o contexto do intervalo com a medição da métrica.

    Por exemplo, a função computeSubrequests segue a orientação anterior. A função subRequestsHistogram.Record é invocada depois de 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 essa amostra, consulte Adicionar rastreamentos e métricas personalizados ao seu app.

A seguir