Correlacionar métricas y trazas mediante ejemplares

En este documento se describen los ejemplares, que son puntos de datos de ejemplo asociados a un punto de datos de una métrica. Una de las funciones de los ejemplares es almacenar un enlace a un rastreo, lo que te permite correlacionar tus datos de métricas y de rastreo. En este documento también se describe cómo puedes usar OpenTelemetry para generar ejemplares.

Acerca de los ejemplares

Los ejemplares son una forma de asociar datos arbitrarios con datos de métricas. Puede usarlas para asociar datos no métricos a las mediciones. Una de las aplicaciones de los ejemplares es asociar datos de traza con datos de métricas. En Cloud Monitoring, los ejemplares se pueden adjuntar a datos de métricas que tengan el tipo de valor Distribution. Las métricas con valores de distribución recogen muchas mediciones y las agrupan en contenedores. Cada "punto" es un histograma, que es una matriz que muestra el recuento de los segmentos. Las mediciones reales no se conservan, solo los recuentos de los contenedores. Para obtener más información, consulta el artículo Acerca de las métricas con valores de distribución.

Cuando se escribe un punto de datos de métrica, se puede adjuntar a esos datos un array de objetos Exemplar. Cuando se usan ejemplares, se adjunta información útil a los datos de métricas. Por ejemplo, cuando OpenTelemetry escribe un ejemplar, adjunta un enlace al intervalo de un rastreo actual.

Los datos de histogramas suelen mostrarse mediante un mapa de calor. Cuando un "punto" contiene un ejemplar, Cloud Monitoring anota el mapa de calor con un punto:

  • Para ver un resumen de la información sobre el punto de la métrica, activa la descripción emergente de la anotación.
  • Para acceder al trazo, selecciona la anotación.

Por ejemplo, el ejemplo de instrumentación de Go usa OpenTelemetry para escribir datos de métricas, datos de trazas y ejemplares. En la siguiente captura de pantalla se muestra el valor de la métrica prometheus/http_server_duration_milliseconds/histogram después de varias ejecuciones de la aplicación:

Ejemplo de un mapa de calor que muestra varios ejemplares.

En la captura de pantalla anterior se muestran varios ejemplos. Se muestra la descripción emergente de un ejemplar, que incluye la fecha, el nombre del rastreo, los percentiles y un valor de latencia.

Cuando se selecciona la anotación, se muestra el seguimiento vinculado en el ejemplar:

Ejemplo de los detalles de la traza de un ejemplar.

Si la información que se muestra no es lo suficientemente detallada, puedes seleccionar Ver en traza, que abre la página Explorador de trazas. En esa página, puede ver los atributos de la traza y acceder a los enlaces de las entradas de registro.

Cómo habilitar ejemplares de OpenTelemetry

Como se muestra en el ejemplo anterior, puede configurar OpenTelemetry para escribir ejemplares que vinculen el span actual de un rastreo a una medición de métricas. Sin embargo, para que se escriban ejemplos, debes hacer lo siguiente:

  1. Configura los SDKs de métricas y de trazas de OpenTelemetry.

  2. Para incluir ejemplares en tu instrumentación personalizada, asegúrate de que la métrica se registre en un intervalo y de que transfieras el contexto del intervalo con la medición de la métrica.

    Por ejemplo, la función computeSubrequests sigue las directrices anteriores. La función subRequestsHistogram.Record se invoca después de tracer.Start y antes de span.End, que se aplaza. También ten en cuenta que el contexto, ctx, se transfiere de tracer.Start a la función 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 obtener más información sobre esta muestra, consulta Añadir métricas y trazas personalizadas a tu aplicación.

Siguientes pasos