Agrega métricas y seguimientos personalizados a tu app con OpenTelemetry

En este documento, se describe cómo agregar código de observabilidad a tu aplicación usando OpenTelemetry. OpenTelemetry proporciona bibliotecas de instrumentación que generan telemetría para frameworks populares. Puedes aumentar la telemetría generada por la biblioteca si agregas instrumentación personalizada que mida el comportamiento específico de la aplicación.

Los principios y conceptos que se describen en este documento se pueden aplicar a las apps escritas en todos los lenguajes compatibles con OpenTelemetry. Para obtener más información sobre la instrumentación, consulta los siguientes documentos:

El código de muestra, que es la misma app de Go que se describe en Genera seguimientos y métricas con Go, está disponible en GitHub. Para ver la muestra completa, haz clic en Más y, luego, selecciona Ver en GitHub.

Antes de comenzar

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Crea seguimientos personalizados

Para generar seguimientos personalizados desde tu aplicación, agrega código de instrumentación que crea intervalos de OpenTelemetry. En OpenTelemetry, los intervalos son los componentes básicos de los seguimientos.

Para crear un intervalo, haz lo siguiente:

  1. Modifica tu app para adquirir un Tracer de OpenTelemetry. En OpenTelemetry, un rastreador es un creador de intervalos. Puedes adquirir un rastreador como se muestra en el siguiente código:

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    El nombre del rastreador, que se representa con scopeName, identifica el alcance de la instrumentación de los seguimientos generados.

  2. Usa la instancia tracer para crear intervalos. En el siguiente código de muestra, la función computeSubrequests genera un intervalo cada vez que se la llama:

    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
}

    En la muestra de código anterior, el intervalo generado a partir de la función computeSubrequests representa el trabajo que realizó toda la función. Esto se debe a que el primer paso de la función es iniciar un intervalo nuevo usando tracer.Start, y la palabra clave defer antes de span.End() garantiza que el intervalo finalice justo antes de que salga la función.

Crea métricas personalizadas

Para generar metricas desde la aplicación, agrega un código de instrumentación que registre las mediciones realizadas durante la ejecución de la app.

Para crear métricas, haz lo siguiente:

  1. Modifica tu app para adquirir un Meter de OpenTelemetry. En OpenTelemetry, un medidor proporciona acceso a instrumentos de métricas para registrar métricas. Puedes adquirir un medidor como se muestra en el siguiente código:

    const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"

var (
	meter                = otel.Meter(scopeName)
	tracer               = otel.Tracer(scopeName)
	sleepHistogram       metric.Float64Histogram
	subRequestsHistogram metric.Int64Histogram
)

    El nombre del medidor, que se representa con scopeName, identifica el alcance de la instrumentación de las métricas generadas.

  2. Usa la instancia meter para crear instrumentos que puedan registrar métricas. Por ejemplo, en el siguiente código, usamos meter para crear un histograma de OpenTelemetry:

    sleepHistogram, err = meter.Float64Histogram("example.sleep.duration",
	metric.WithDescription("Sample histogram to measure time spent in sleeping"),
	metric.WithExplicitBucketBoundaries(0.05, 0.075, 0.1, 0.125, 0.150, 0.2),
	metric.WithUnit("s"))
if err != nil {
	panic(err)
}

    Este código anterior genera un histograma llamado sleepHistogram.

  3. Usa la instancia sleepHistogram para registrar el tiempo de suspensión, que se determina cuando se invoca la función randomSleep:

    func randomSleep(r *http.Request) time.Duration {
	// simulate the work by sleeping 100 to 200 ms
	sleepTime := time.Duration(100+rand.Intn(100)) * time.Millisecond
	time.Sleep(sleepTime)

	hostValue := attribute.String("host.value", r.Host)
	// custom histogram metric to record time slept in seconds
	sleepHistogram.Record(r.Context(), sleepTime.Seconds(), metric.WithAttributes(hostValue))
	return sleepTime
}

    Las métricas registradas de estos instrumentos se exportan desde tu aplicación en función de la configuración del exportador de OpenTelemetry.

¿Qué sigue?