Correlaciona las métricas y los seguimientos con ejemplares

En este documento, se describen ejemplares, que son datos de ejemplo adjuntos a un dato de métrica. Uno de los ejemplares es almacenar un vínculo a un seguimiento, que te permite correlacionar tus datos de seguimiento y métrica. 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. Puedes usarlos para adjuntar datos no métricas a las mediciones. Uno de los usos de los ejemplares es asociar datos de seguimiento con datos de métricas. En Cloud Monitoring, los ejemplos se pueden adjuntar a datos de métricas que tienen el tipo de valor Distribution. Las métricas con valor de distribución recopilan muchas mediciones y las agrupan en buckets. Cada “punto” es un histograma, que es un array que enumera recuentos de buckets. No se conservan las mediciones reales, solo los recuentos de buckets. Para obtener más información, consulta Acerca de las métricas con valor de distribución.

Cuando se escriben datos de métricas, se puede adjuntar un array de objetos Exemplar a esos datos. Los ejemplares, cuando se usan, adjuntan información útil a los datos de las métricas. Por ejemplo, cuando OpenTelemetry escribe un ejemplar, adjunta un vínculo al intervalo de seguimiento actual de un seguimiento.

Por lo general, los datos del histograma se muestran usando un mapa de calor. Cuando un “punto” contiene un ejemplar, Cloud Monitoring anota el mapa de calor con un punto:

  • Para ver la información resumida sobre el punto de métrica, activa la información sobre la herramienta de la anotación.
  • Para acceder al seguimiento, selecciona la anotación.

Por ejemplo, la aplicación de muestra descrita en Genera seguimientos y métricas con Go usa OpenTelemetry para escribir datos de métricas, datos de seguimiento 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 en el que se muestran varios ejemplares.

En la captura de pantalla anterior, se muestran varios ejemplares. La información sobre la herramienta de un ejemplar está expandida y muestra la fecha, el nombre de seguimiento, 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 seguimiento de un ejemplar.

Cuando la información que se muestra no está lo suficientemente detallada, puedes seleccionar Ver en Trace, que abre la página Explorador de Trace. En esa página, puedes ver los atributos de seguimiento y los vínculos de acceso a las entradas de registro.

Cómo habilitar ejemplares de OpenTelemetry

Como se ilustra en el ejemplo anterior, puedes configurar OpenTelemetry para escribir ejemplares que vinculen el intervalo actual de un seguimiento a una medición de métrica. Sin embargo, para que se escriban ejemplares, debes hacer lo siguiente:

  1. Configurar la métrica de OpenTelemetry y los SDK de seguimiento

  2. Para incluir ejemplos en tu instrumentación personalizada, asegúrate de que la métrica esté registrada en un intervalo y de pasar el contexto del intervalo con la medición de la métrica.

    Por ejemplo, la función computeSubrequests sigue la guía anterior. La función subRequestsHistogram.Record se invoca después de tracer.Start y antes de span.End, que se aplaza. Observa también que el contexto, ctx, se pasa 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 Agrega seguimientos y métricas personalizados a tu app.

¿Qué sigue?