Aggiungere tracce e metriche personalizzate all'app con OpenTelemetry

L'aggiunta di strumentazione OpenTelemetry personalizzata al codice dell'applicazione consente di registrare intervalli di traccia e metriche personalizzati che misurano il comportamento specifico dell'applicazione oltre a ciò che raccolgono le librerie del framework standard. Puoi applicare i concetti di questo documento alle applicazioni scritte in qualsiasi linguaggio supportato da OpenTelemetry. Per informazioni di base, consulta Osservabilità per gli sviluppatori di applicazioni e Scegli un approccio di strumentazione.

Gli esempi in questo documento utilizzano l'applicazione di esempio Go descritta in Esempio di strumentazione Go, disponibile su GitHub.

Prima di iniziare

Abilita le API Cloud Logging, Cloud Monitoring e Cloud Trace, se non sono già abilitate.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Crea tracce personalizzate

Per generare tracce personalizzate dalla tua applicazione, aggiungi il codice di strumentazione che crea intervalli OpenTelemetry. In OpenTelemetry, gli intervalli sono i componenti di base delle tracce.

Per creare un intervallo:

  1. Modifica l'app per acquisire un Tracer OpenTelemetry. In OpenTelemetry, un tracer è un creatore di intervalli. Puoi acquisire un tracciatore come mostrato nel codice seguente. Per visualizzare l'esempio completo, seleziona il logo di GitHub nella barra degli strumenti dell'esempio.

    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 gli intervalli. Nel seguente esempio di codice, la funzione computeSubrequests genera uno span 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, lo span 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 che span.End() garantisca che l'intervallo termini subito prima dell'uscita dalla funzione.

Crea metriche personalizzate

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

Per creare le metriche, segui questi passaggi:

  1. Modifica l'app per acquisire un Meter OpenTelemetry. In OpenTelemetry, un meter fornisce l'accesso agli strumenti di metrica per la registrazione delle metriche. Puoi acquisire un misuratore come mostrato 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 meter, 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, il seguente codice utilizza 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 l'ora del sonno, che viene determinata 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 dalla tua applicazione in base alla configurazione dell'esportatore OpenTelemetry.

Passaggi successivi