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 gängige Frameworks generieren. Sie können die von der Bibliothek generierte Telemetrie ergänzen, indem Sie benutzerdefinierte Instrumentierung hinzufügen, mit der das anwendungsspezifische Verhalten gemessen wird.

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

Der Beispielcode, der der Go-App entspricht, die unter Traces und Messwerte mit Go generieren beschrieben wird, ist auf GitHub verfügbar. Wenn Sie sich das vollständige Beispiel ansehen 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.

Enable the APIs

Benutzerdefinierte Traces erstellen

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

So erstellen Sie einen Abschnitt:

  1. Ändern Sie Ihre App so, dass eine OpenTelemetry-Tracer abgerufen wird. In OpenTelemetry ist ein Tracer der 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, gibt den Instrumentierungsumfang der generierten Traces an.

  2. Verwenden Sie die tracer-Instanz, um Spannen zu erstellen. Im folgenden Codebeispiel generiert die Funktion computeSubrequests jedes Mal, wenn sie aufgerufen wird, einen Span:

    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 steht der von der computeSubrequests-Funktion generierte Bereich für die gesamte Funktion. Das liegt daran, dass im ersten Schritt der Funktion eine neue Span mit tracer.Start und dem Schlüsselwort defer gestartet wird, bevor die Span mit span.End() direkt vor dem Ende der Funktion beendet wird.

Benutzerdefinierte Messwerte erstellen

Wenn Sie Messwerte aus Ihrer Anwendung generieren möchten, fügen Sie Instrumentierungscode hinzu, mit dem Messungen während der Ausführung Ihrer App erfasst werden.

So erstellen Sie Messwerte:

  1. Ändern Sie Ihre App so, dass eine OpenTelemetry-Meter abgerufen wird. In OpenTelemetry bietet ein Messgerät Zugriff auf Messinstrumente zum Erfassen von Messwerten. Sie können einen Messwert wie im folgenden Code erfassen:

    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 Messwertname, der durch scopeName dargestellt wird, gibt den Instrumentierungsumfang 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 diesem Code wird ein Histogramm mit dem Namen sleepHistogram generiert.

  3. Verwenden Sie die Instanz sleepHistogram, um die Ruhezeit 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 erfassten Messwerte aus diesen Instrumenten werden basierend auf der Konfiguration Ihres OpenTelemetry-Exporters aus Ihrer Anwendung exportiert.

Nächste Schritte