Benutzerdefinierte Traces und Messwerte in Ihre Anwendung einfügen

Wenn Sie Ihrem Anwendungscode eine benutzerdefinierte OpenTelemetry-Instrumentierung hinzufügen, können Sie benutzerdefinierte Trace-Spans und Messwerte aufzeichnen, die das anwendungsspezifische Verhalten über das hinaus messen, was von Standard-Framework-Bibliotheken erfasst wird. Sie können die Konzepte in diesem Dokument auf Anwendungen anwenden, die in einer von OpenTelemetry unterstützten Sprache geschrieben wurden. Hintergrundinformationen finden Sie unter Beobachtbarkeit für Anwendungsentwickler und Instrumentierungsansatz auswählen.

In den Beispielen in diesem Dokument wird die Go-Beispielanwendung verwendet, die im Go-Instrumentierungsbeispiel beschrieben wird und in GitHub verfügbar ist.

Hinweis

Aktivieren Sie die Cloud Logging, Cloud Monitoring und Cloud Trace APIs, falls sie noch nicht aktiviert sind.

Erforderliche Rollen zum Aktivieren von APIs

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

APIs aktivieren

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

  1. Ändern Sie Ihre App so, dass ein OpenTelemetry-Tracer abgerufen wird. In OpenTelemetry ist ein Tracer ein Ersteller von Spans. Sie können einen Tracer, wie im folgenden Code gezeigt, abrufen: Wenn Sie das vollständige Beispiel sehen möchten, wählen Sie in der Symbolleiste des Beispiels das GitHub-Logo aus.

    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 Tracername, 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 Span 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 Span gestartet wird. Das Keyword defer vor span.End() sorgt dafür, dass der Span 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 ein OpenTelemetry-Meter abgerufen wird. In OpenTelemetry bietet ein Messtool Zugriff auf Messinstrumente zum Aufzeichnen von Messwerten. Sie können ein Messtool 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 Name des Messtools, 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 wird beispielsweise meter verwendet, 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 namens sleepHistogram generiert.

  3. Verwenden Sie die sleepHistogram-Instanz, um die Schlafdauer 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 von diesen Instrumenten aufgezeichneten Messwerte werden entsprechend Ihrer OpenTelemetry-Exporter-Konfiguration aus der Anwendung exportiert.

Nächste Schritte