Agrega métricas y seguimientos personalizados a tu app

Agregar instrumentación personalizada de OpenTelemetry al código de tu aplicación te permite registrar intervalos de seguimiento y métricas personalizados que miden el comportamiento específico de la aplicación más allá de lo que recopilan las bibliotecas de frameworks estándar. Puedes aplicar los conceptos de este documento a las aplicaciones escritas en cualquier lenguaje compatible con OpenTelemetry. Para obtener información general, consulta Observabilidad para desarrolladores de aplicaciones y Elige un enfoque de instrumentación.

En los ejemplos de este documento, se usa la aplicación de muestra de Go que se describe en Muestra de instrumentación de Go, que está disponible en GitHub.

Antes de comenzar

Habilita las APIs de Cloud Logging, Cloud Monitoring y Cloud Trace, si aún no están habilitadas.

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

Habilitar las API

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. Para ver la muestra completa, selecciona el logotipo de GitHub en la barra de herramientas de la muestra.

    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 la siguiente muestra de código, 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, se usa 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 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?