Añadir métricas y trazas personalizadas a tu aplicación

En este documento se describe cómo añadir código de observabilidad a una aplicación mediante OpenTelemetry. OpenTelemetry proporciona bibliotecas de instrumentación que generan telemetría para frameworks populares. Puedes aumentar la telemetría generada por la biblioteca añadiendo instrumentación personalizada que mida el comportamiento específico de tu aplicación.

Los principios y conceptos descritos en este documento se pueden aplicar a aplicaciones escritas en todos los lenguajes admitidos por OpenTelemetry. Para obtener más información sobre la instrumentación, consulta los siguientes documentos:

El código de muestra, que es la misma aplicación Go que se describe en el ejemplo de instrumentación de Go, está disponible en GitHub. Para ver el ejemplo completo, haz clic en Más y, a continuación, selecciona Ver en GitHub.

Antes de empezar

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Crear trazas personalizadas

Para generar traces personalizados desde tu aplicación, añade código de instrumentación que cree intervalos de OpenTelemetry. En OpenTelemetry, los spans son los componentes fundamentales de las trazas.

Para crear un intervalo, sigue estos pasos:

  1. Modifica tu aplicación para adquirir un Tracer de OpenTelemetry. En OpenTelemetry, un tracer es un creador de spans. Puedes obtener un tracer 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, representado por scopeName, identifica el ámbito de instrumentación de los rastreos generados.

  2. Usa la instancia tracer para crear intervalos. En el siguiente código de ejemplo, la función computeSubrequests genera un elemento "span" cada vez que se 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 el ejemplo de código anterior, el intervalo generado a partir de la función computeSubrequests representa el trabajo realizado por toda la función. Esto se debe a que el primer paso de la función es iniciar un nuevo intervalo con tracer.Start y la palabra clave defer antes de que span.End() asegure que el intervalo finalice justo antes de que se cierre la función.

Crear métricas personalizadas

Para generar métricas de tu aplicación, añade código de instrumentación que registre las mediciones tomadas durante la ejecución de tu aplicación.

Para crear métricas, siga estos pasos:

  1. Modifica tu aplicación para adquirir un Meter de OpenTelemetry. En OpenTelemetry, un contador 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 contador, representado por scopeName, identifica el ámbito de 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)
}

    El código anterior genera un histograma llamado sleepHistogram.

  3. Usa la instancia sleepHistogram para registrar el tiempo de sueño, 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.

Siguientes pasos