Correlacionar métricas e traces usando exemplos

Este documento descreve 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 trace, o que permite correlacionar os dados de métrica e de trace. Este documento também descreve como usar o OpenTelemetry para gerar exemplos.

Sobre os exemplos

Os exemplares são uma maneira de associar dados arbitrários a dados de métricas. Você pode usá-los para anexar dados não métricos a medições. Um uso de exemplares é associar dados de rastreamento a dados de métrica. No Cloud Monitoring, os exemplos podem ser anexados a dados de métricas com 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 bucket. As medidas reais não são retidas, apenas as contagens de bucket. Para mais informações, consulte Sobre as métricas de valor de distribuição.

Quando um ponto de dados de métrica é 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 exemplo, ele anexa um link ao período atual de um rastro.

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 resumidas sobre o ponto de métrica, ative a dica de ferramenta para a anotação.
  • Para acessar o rastro, selecione a anotação.

Por exemplo, o exemplo de instrumentação do Go usa o OpenTelemetry para gravar dados de métricas, dados de rastreamento e exemplos. 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 mapa de calor que mostra vários exemplos.

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

Quando a anotação é selecionada, o rastro vinculado no exemplo é exibido:

Exemplo dos detalhes do trace de um exemplo.

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

Como ativar exemplos do OpenTelemetry

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

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

  2. Para incluir exemplos na sua instrumentação personalizada, garanta que a métrica seja registrada em 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 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 este exemplo, consulte Adicionar rastreamentos e métricas personalizados ao seu app.

A seguir