Aggiungere tracce e metriche personalizzate all'app

Questo documento descrive come aggiungere codice di osservabilità all'applicazione utilizzando OpenTelemetry. OpenTelemetry fornisce librerie di strumentazione che generano telemetria per i framework più diffusi. Puoi aumentare la telemetria generata dalla libreria aggiungendo strumenti personalizzati che misurano 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 scoprire di più sulla misurazione, consulta i seguenti documenti:

Il codice campione, ovvero la stessa app Go descritta in Genera tracce e metriche con Go, è disponibile su GitHub. Per visualizzare l'esempio completo, fai clic su Altro e poi seleziona Visualizza su GitHub.

Prima di iniziare

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

Enable the APIs

Creare tracce personalizzate

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

Per creare un intervallo:

  1. Modifica l'app per acquisire un token OpenTelemetry Tracer. In OpenTelemetry, un tracer è un creatore di span. Puoi acquisire un tracker 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 tracciante, rappresentato da scopeName, identifica l'ambito dell'instrumentazione delle tracce generate.

  2. Utilizza l'istanza tracer per creare gli spazi. Nel seguente esempio di codice, la funzione computeSubrequests genera uno spazio 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 funzionecomputeSubrequests rappresenta il lavoro svolto dall'intera funzione. Questo perché il primo passaggio della funzione consiste nell'iniziare un nuovo span utilizzando tracer.Start e la parola chiave defer prima che span.End() garantisca il termine dello span appena prima dell'uscita della funzione.

Creare 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:

  1. Modifica l'app per acquisire un token OpenTelemetry Meter. In OpenTelemetry, un metro fornisce l'accesso agli strumenti metrici per registrare le metriche. Puoi acquisire un contatore 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 contatore, rappresentato da scopeName, identifica l'ambito dell'instrumentazione delle metriche generate.

  2. Utilizza l'istanza meter per creare strumenti che possono registrare le metriche. Ad esempio, nel codice seguente 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)
}

    Questo codice precedente genera un'istogramma denominato sleepHistogram.

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