Mit OpenTelemetry-Tracing können Sie die Latenz verschiedener Pub/Sub-Clientbibliotheksvorgänge wie Batching, Lease-Verwaltung und Ablaufsteuerung identifizieren und nachvollziehen. Das Erfassen dieser Informationen kann Ihnen bei der Fehlerbehebung von Clientbibliotheks-Problemen helfen.
Hier einige mögliche Anwendungsfälle für OpenTelemetry-Tracing:
- Bei Ihrem Dienst tritt eine höhere Veröffentlichungslatenz als normal auf.
- Sie haben eine hohe Anzahl von erneuten Zustellungen von Nachrichten.
- Eine Änderung an der Callback-Funktion des Abonnentenclients führt dazu, dass die Verarbeitung länger als gewöhnlich dauert.
Hinweise
Führen Sie vor dem Konfigurieren von OpenTelemetry die folgenden Aufgaben aus:
- Richten Sie Pub/Sub mit einer der Clientbibliotheken ein.
- Installieren Sie das OpenTelemetry SDK und richten Sie einen Trace-Exporter und einen Tracer-Anbieter ein.
- Aktivieren Sie die Cloud Trace API.
- Cloud Observability-Traces lesen
Erforderliche Rollen
Damit das Dienstkonto die erforderlichen Berechtigungen zum Exportieren von Traces nach Cloud Trace hat, bitten Sie Ihren Administrator, dem Dienstkonto die folgenden IAM-Rollen für Ihr Projekt zu gewähren:
-
Alle:
Cloud Trace-Agent (
roles/cloudtrace.agent
)
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.
Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Exportieren von Traces nach Cloud Trace erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen
Die folgenden Berechtigungen sind erforderlich, um Traces in Cloud Trace zu exportieren:
-
Alle:
cloudtrace.traces.patch
Ihr Administrator kann dem Dienstkonto möglicherweise auch diese Berechtigungen mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erteilen.
OpenTelemetry-Tracing-Workflow
Zum Einrichten von OpenTelemetry-Tracing verwenden Sie die Pub/Sub-Clientbibliotheken und das OpenTelemetry SDK. Mit dem SDK müssen Sie einen Trace-Exporter und einen Tracer-Provider einrichten, bevor Sie eine Verbindung zu den Pub/Sub-Bibliotheken herstellen. In einigen Bibliotheken ist das Einrichten eines Tracer-Anbieters optional.
Trace-Exporter: Das OpenTelemetry SDK verwendet den Trace-Exporter, um zu bestimmen, wohin Traces gesendet werden sollen.
Tracer-Anbieter: Die Pub/Sub-Clientbibliotheken verwenden den Tracer-Provider, um Traces zu erstellen.
Mit den folgenden Schritten können Sie das Tracing einrichten:
- Instanziieren Sie einen Cloud Trace OpenTelemetry-Exporter.
- Instanziieren und registrieren Sie bei Bedarf einen Tracer-Provider mit dem OpenTelemetry SDK.
- Konfigurieren Sie Ihren Client mit der Option „OpenTelemetry-Tracing aktivieren“.
- Pub/Sub-Clientbibliotheken zum Veröffentlichen einer Nachricht verwenden
So funktioniert die Routenaufzeichnung
Für jede veröffentlichte Nachricht wird in der Clientbibliothek ein neuer Trace erstellt. Dieser Trace stellt den gesamten Lebenszyklus der Nachricht dar, vom Zeitpunkt der Veröffentlichung bis zur Bestätigung. Ein Trace enthält Informationen wie die Dauer von Vorgängen, übergeordnete und untergeordnete Spans sowie verknüpfte Spans.
Ein Trace besteht aus einem Stamm-Span und den entsprechenden untergeordneten Spans. Diese Spannen stellen die Arbeit dar, die die Clientbibliothek bei der Verarbeitung einer Nachricht ausführt. Jedes Message-Trace enthält Folgendes:
- Zur Veröffentlichung: Flusssteuerung, Planung von Sortierschlüsseln, Batching und die Länge des Publish-RPC.
- Für Abos Gleichzeitigkeitserkennung, Planung von Bestellschlüsseln und Verwaltung von Leases.
Damit Informationen von der Veröffentlichungs- zur Abonnentenseite übertragen werden, fügen die Clientbibliotheken auf der Veröffentlichungsseite ein Attribut für das Tracing ein. Der Mechanismus zur Kontextweitergabe wird nur aktiviert, wenn das Tracing aktiviert ist und das Präfix googclient_
vorangestellt wird.
Nachrichten mit Tracing veröffentlichen
Das folgende Codebeispiel zeigt, wie Sie das Tracing mit der Pub/Sub-Clientbibliothek und dem OpenTelemetry SDK aktivieren. In diesem Beispiel werden die Tracing-Ergebnisse nach Cloud Trace exportiert.
Hinweise
Beim Instanziieren des Tracer-Anbieters konfigurieren Sie mit dem OpenTelemetry SDK ein Sampling-Verhältnis. Dieses Verhältnis bestimmt, wie viele Traces das SDK erfassen soll. Eine niedrigere Samplingrate kann dazu beitragen, die Abrechnungskosten zu senken und zu verhindern, dass Ihr Dienst das Cloud Trace-Kontingent für Spans überschreitet.
Go
C++
Python
Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Python in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Python API.
TypeScript
Node.js
Java
Nachrichten mit Tracing empfangen
Go
C++
Python
TypeScript
Node.js
Java
Trace analysieren
In den folgenden Abschnitten finden Sie detaillierte Informationen dazu, wie Sie einen Trace in der Google Cloud -Konsole nachverfolgen und analysieren.
Hinweise
- Wenn Sie einen Batch von Nachrichten veröffentlichen, wird der RPC-Span für die Veröffentlichung in einem separaten Trace erfasst.
- Ein Publish-RPC hat mehrere Ursprungsbereiche, da mehrere Create-Aufrufe zu einem Publish-RPC führen können, wenn sie zusammengefasst werden.
Spans in OpenTelemetry können null oder einen übergeordneten Span haben.
Spans, die Batchvorgänge darstellen, z. B. publish batch (die logischerweise mehrere parents haben sollten), können nicht mit null oder einem übergeordneten Span dargestellt werden.
Spannen verfolgen, die während des Nachrichtenlebenszyklus erstellt wurden
Das folgende Bild zeigt ein Beispiel für Spans, die in einem einzelnen Trace für eine einzelne Nachricht erstellt werden.
Jeder Bereich kann zusätzliche Attribute haben, die zusätzliche Informationen wie die Byte-Größe der Nachricht und Informationen zum Bestellschlüssel enthalten.
Spannenattribute enthalten zusätzliche Metadaten wie den Sortierschlüssel, die Nachrichten-ID und die Größe der Nachricht.
Die Hauptspannen für das Veröffentlichen und Abonnieren werden mit Spannenereignissen erweitert, die dem Zeitpunkt entsprechen, zu dem ein Netzwerkaufruf ausgegeben und abgeschlossen wird.
Häufige Probleme beheben
Die folgenden Probleme können zu Problemen mit dem Tracing führen:
- Das Dienstkonto, das Sie zum Exportieren von Traces verwenden, hat nicht die erforderliche Rolle
roles/cloudtrace.agent
. - Das Kontingent für die maximale Anzahl der aufgenommenen Spans in Cloud Trace wurde erreicht.
- Ihre Anwendung wird beendet, ohne die entsprechende Flush-Funktion aufzurufen.