Benutzerdefinierte Traces und Messwerte in Ihre Anwendung einfügen

In diesem Dokument wird beschrieben, wie Sie Ihrer Anwendung mithilfe von OpenTelemetry Code zur Beobachtbarkeit hinzufügen. OpenTelemetry bietet Instrumentierungsbibliotheken, die Telemetrie für beliebte Frameworks generieren. Sie können die von der Bibliothek generierte Telemetrie durch benutzerdefinierte Instrumentierung ergänzen, mit der das anwendungsspezifische Verhalten gemessen wird.

Die in diesem Dokument beschriebenen Grundsätze und Konzepte können auf Apps angewendet werden, die in allen von OpenTelemetry unterstützten Sprachen geschrieben wurden. Weitere Informationen zur Instrumentierung finden Sie in den folgenden Dokumenten:

Der Beispielcode, der mit der in Go-Instrumentierungsbeispiel beschriebenen Go-App identisch ist, ist in GitHub verfügbar. Wenn Sie das vollständige Beispiel sehen möchten, klicken Sie auf  Mehr und wählen Sie dann Auf GitHub ansehen aus.

Hinweise

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

Benutzerdefinierte Traces erstellen

Wenn Sie benutzerdefinierte Traces aus Ihrer Anwendung generieren möchten, fügen Sie Instrumentierungscode hinzu, der OpenTelemetry-Spans erstellt. In OpenTelemetry sind Spans die Bausteine für Traces.

So erstellen Sie einen Bereich:

  1. Ändern Sie Ihre App so, dass eine OpenTelemetry-Tracer abgerufen wird. In OpenTelemetry ist ein Tracer ein Ersteller von Spans. Sie können einen Tracer wie im folgenden Code gezeigt abrufen:

    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
)

    Der Tracer-Name, der durch scopeName dargestellt wird, identifiziert den Instrumentierungsbereich der generierten Traces.

  2. Verwenden Sie die tracer-Instanz, um Spans zu erstellen. Im folgenden Codebeispiel wird mit der Funktion computeSubrequests bei jedem Aufruf ein Bereich generiert:

    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
}

    Im vorherigen Codebeispiel stellt der von der Funktion computeSubrequests generierte Bereich die Arbeit dar, die von der gesamten Funktion ausgeführt wird. Das liegt daran, dass im ersten Schritt der Funktion mit tracer.Start ein neuer Bereich gestartet wird. Das Keyword defer vor span.End() sorgt dafür, dass der Bereich beendet wird, kurz bevor die Funktion beendet wird.

Benutzerdefinierte Messwerte erstellen

Um Messwerte aus Ihrer Anwendung zu generieren, fügen Sie Instrumentierungscode hinzu, der während der Ausführung Ihrer App vorgenommene Messungen aufzeichnet.

So erstellen Sie Messwerte:

  1. Ändern Sie Ihre App so, dass eine OpenTelemetry-Meter abgerufen wird. In OpenTelemetry bietet ein Meter Zugriff auf Messwertinstrumente zum Aufzeichnen von Messwerten. Sie können einen Zähler wie im folgenden Code gezeigt abrufen:

    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
)

    Der Zählernamen, der durch scopeName dargestellt wird, gibt den Instrumentierungsbereich der generierten Messwerte an.

  2. Verwenden Sie die meter-Instanz, um Instrumente zu erstellen, mit denen Messwerte erfasst werden können. Im folgenden Code verwenden wir beispielsweise meter, um ein OpenTelemetry-Histogramm zu erstellen:

    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)
}

    Mit dem vorherigen Code wird ein Histogramm mit dem Namen sleepHistogram generiert.

  3. Verwenden Sie die sleepHistogram-Instanz, um die Schlafzeit aufzuzeichnen, die beim Aufrufen der Funktion randomSleep ermittelt wird:

    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
}

    Die aufgezeichneten Messwerte dieser Instrumente werden basierend auf Ihrer OpenTelemetry-Exporterkonfiguration aus Ihrer Anwendung exportiert.

Nächste Schritte