Correlacione métricas e rastreios através de exemplos

Este documento descreve os exemplos, que são pontos de dados de exemplo anexados a um ponto de dados de métricas. Uma das utilizações dos exemplos é armazenar um link para um rastreio, o que lhe permite correlacionar os dados de métricas e rastreios. Este documento também descreve como pode usar o OpenTelemetry para gerar exemplos.

Acerca dos exemplos

Os exemplares são uma forma de associar dados arbitrários a dados de métricas. Pode usá-las para anexar dados não métricos a medições. Uma das utilizações dos exemplares é associar dados de rastreio a dados de métricas. No Cloud Monitoring, os exemplares podem ser anexados a dados de métricas com o tipo de valor Distribution. As métricas com valor de distribuição recolhem muitas medições e agrupam-nas em contentores. Cada "ponto" é um histograma, que é uma matriz que apresenta as contagens de intervalos. As medições reais não são retidas, apenas as contagens dos grupos. Para mais informações, consulte o artigo Acerca das métricas com valores de distribuição.

Quando um ponto de dados de métricas é escrito, é possível anexar uma matriz de objetos Exemplar a esses dados. Os exemplares, quando usados, anexam informações úteis aos dados das métricas. Por exemplo, quando o OpenTelemetry escreve um exemplar, anexa um link ao intervalo de um rastreio atual.

Normalmente, os dados do histograma são apresentados através de um mapa térmico. Quando um "ponto" contém um exemplar, o Cloud Monitoring anota o mapa de calor com um ponto:

  • Para ver informações de resumo sobre o ponto da métrica, ative a sugestão para a anotação.
  • Para aceder ao traçado, selecione a anotação.

Por exemplo, o exemplo de instrumentação do Go usa o OpenTelemetry para escrever dados de métricas, dados de rastreio e exemplares. A captura de ecrã seguinte mostra o valor da métrica prometheus/http_server_duration_milliseconds/histogram após várias execuções da aplicação:

Exemplo de um mapa térmico que mostra vários exemplos.

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

Quando a anotação é selecionada, é apresentado o rastreio associado no exemplo:

Exemplo dos detalhes do rastreio de um exemplar.

Quando as informações apresentadas não são suficientemente detalhadas, pode selecionar Ver no Trace, que abre a página Explorador de rastreios. Nessa página, pode ver os atributos de rastreio e aceder a links para entradas de registo.

Como ativar os exemplares do OpenTelemetry

Como ilustra o exemplo anterior, pode configurar o OpenTelemetry para escrever exemplos que associem o intervalo atual de um rastreio a uma medição métrica. No entanto, para escrever exemplos, tem de fazer o seguinte:

  1. Configure os SDKs de métricas e rastreio do OpenTelemetry.

  2. Para incluir exemplos na sua instrumentação personalizada, certifique-se de que a métrica é registada num intervalo, e que passa o contexto do intervalo 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. Tenha também em atenção 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 acerca deste exemplo, consulte o artigo Adicione rastreios e métricas personalizados à sua app.

O que se segue?