Aggiungere tracce e metriche personalizzate all'app con OpenTelemetry

Questo documento descrive come aggiungere codice di osservabilità all'applicazione utilizzando OpenTelemetry. OpenTelemetry fornisce librerie di strumentazione che generano dati di telemetria per i framework più diffusi. Puoi aumentare i dati di telemetria generati dalla libreria aggiungendo una strumentazione personalizzata che misura il comportamento specifico dell'applicazione.

I principi e i concetti descritti in questo documento possono essere applicati alle app scritte in tutte le lingue supportate da OpenTelemetry. Per saperne di più sulla strumentazione, consulta i seguenti documenti:

Il codice campione, che è la stessa app Go descritta in Esempio di strumentazione Go, è disponibile su GitHub. Per visualizzare l'esempio completo, nella barra degli strumenti dell'esempio seleziona il logo di GitHub.

Prima di iniziare

Abilita le API Cloud Logging, Cloud Monitoring e Cloud Trace.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilita le API

Creare tracce personalizzate

Per generare tracce personalizzate dalla tua applicazione, aggiungi codice di strumentazione che crea intervalli OpenTelemetry. In OpenTelemetry, gli intervalli sono gli elementi costitutivi delle tracce.

Per creare un intervallo:

  1. Modifica l'app per acquisire un OpenTelemetry Tracer. In OpenTelemetry, un tracer è un creatore di intervalli. Puoi acquisire un tracer come illustrato nel seguente codice:

    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
)

    Il nome del tracer, rappresentato da scopeName, identifica l' ambito di strumentazione delle tracce generate.

  2. Utilizza l'istanza tracer per creare intervalli. Nel seguente esempio di codice, la funzione computeSubrequests genera un intervallo ogni volta che viene chiamata:

    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
}

    Nell'esempio di codice precedente, l'intervallo generato dalla funzione computeSubrequests rappresenta il lavoro svolto dall'intera funzione. Questo perché il primo passaggio della funzione consiste nell'avviare un nuovo intervallo utilizzando tracer.Start e la parola chiave defer prima di span.End() garantisce che l'intervallo venga terminato immediatamente prima dell'uscita dalla funzione.

Creare metriche personalizzate

Per generare metriche dalla tua applicazione, aggiungi codice di strumentazione che registra le misurazioni effettuate durante l'esecuzione dell'app.

Per creare metriche:

  1. Modifica l'app per acquisire un OpenTelemetry Meter. In OpenTelemetry, un misuratore fornisce l'accesso agli strumenti di misurazione per la registrazione delle metriche. Puoi acquisire un misuratore come illustrato nel seguente codice:

    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
)

    Il nome del misuratore, rappresentato da scopeName, identifica l' ambito di strumentazione delle metriche generate.

  2. Utilizza l'istanza meter per creare strumenti in grado di registrare le metriche. Ad esempio, nel seguente codice utilizziamo meter per creare un istogramma 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)
}

    Il codice precedente genera un istogramma denominato sleepHistogram.

  3. Utilizza l'istanza sleepHistogram per registrare il tempo di sospensione, che viene determinato quando viene richiamata la funzione 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
}

    Le metriche registrate da questi strumenti vengono esportate dall'applicazione in base alla configurazione dell'esportatore OpenTelemetry.

Passaggi successivi