Mit OpenTelemetry-Tracing können Sie die Latenz verschiedener Pub/Sub-Clientbibliotheksvorgänge wie Batching, Lease-Verwaltung und Ablaufsteuerung identifizieren und nachverfolgen. Diese Informationen können Ihnen bei der Fehlerbehebung in Clientbibliotheken helfen.
Einige mögliche Anwendungsfälle für OpenTelemetry-Tracing:
- Ihr Dienst weist eine höhere Veröffentlichungslatenz als normal auf.
- Es gibt 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.
Hinweis
Bevor Sie OpenTelemetry konfigurieren, führen Sie die folgenden Aufgaben aus:
- Richten Sie Pub/Sub mit einer der Client Bibliotheken ein.
- Installieren Sie das OpenTelemetry SDK und richten Sie einen Trace-Exporter und einen Tracer-Anbieter ein.
- Aktivieren Sie die Cloud Trace API.
- Machen Sie sich mit dem Lesen von Cloud Observability-Traces vertraut.
Erforderliche Rollen
Bitten Sie Ihren Administrator, dem Dienstkonto die folgenden IAM-Rollen für Ihr Projekt zu gewähren, damit das Dienstkonto die erforderlichen Berechtigungen zum Exportieren von Traces nach Cloud Trace hat:
-
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. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:
Erforderliche Berechtigungen
Die folgenden Berechtigungen sind erforderlich, um Traces nach 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-Anbieter einrichten, bevor Sie eine Verbindung zu den Pub/Sub-Bibliotheken herstellen. In einigen Bibliotheken ist die Einrichtung 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-Anbieter, um Traces zu erstellen.
Die folgenden Schritte beschreiben, wie Sie das Tracing einrichten:
- Instanziieren Sie einen Cloud Trace OpenTelemetry-Exporter.
- Instanziieren und registrieren Sie bei Bedarf einen Tracer-Anbieter mit dem OpenTelemetry SDK.
- Konfigurieren Sie Ihren Client mit der Option zum Aktivieren von OpenTelemetry-Tracing.
- Verwenden Sie die Pub/Sub-Clientbibliotheken, um eine Nachricht zu veröffentlichen.
So funktioniert Tracing
Für jede veröffentlichte Nachricht erstellt die Clientbibliothek einen neuen Trace. 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 Spans stellen die Arbeit dar, die die Clientbibliothek bei der Verarbeitung einer Nachricht ausführt. Jeder Nachrichtentrace enthält Folgendes:
- Für die Veröffentlichung Ablaufsteuerung, Planung von Sortierschlüsseln, Batching und die Länge des Veröffentlichungs-RPC.
- Für Abos Gleichzeitigkeitssteuerung, Planung von Sortierschlüsseln und Lease-Verwaltung.
Um Informationen vom Publisher zum Abonnenten weiterzugeben, fügen die Clientbibliotheken auf der Publisher-Seite ein spezifisches Attribut für das Tracing ein. Der Mechanismus zur Kontextweitergabe wird nur aktiviert, wenn das Tracing aktiviert ist. Außerdem wird ihm das Präfix googclient_ vorangestellt.
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 eine Stichprobenrate. Diese Rate bestimmt, wie viele Traces das SDK als Stichprobe erfassen soll. Eine niedrigere Stichprobenrate 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 zum Nachverfolgen und Analysieren eines Traces in der Cloud de Confiance Konsole.
Hinweise
- Beim Veröffentlichen eines Batches von Nachrichten wird der Span des Veröffentlichungs-RPC in einem separaten Trace erfasst.
- Ein Veröffentlichungs-RPC hat mehrere Ursprungs-Spans, da mehrere Erstellungsaufrufe zu einem Veröffentlichungs-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. Batch veröffentlichen, (die logischerweise mehrere übergeordnete Elemente) haben sollten, können nicht mit null oder einem übergeordneten Span dargestellt werden.
Spans nachverfolgen, die während des Lebenszyklus der Nachricht erstellt wurden
Die folgende Abbildung zeigt ein Beispiel für Spans, die in einem einzelnen Trace für eine einzelne Nachricht erstellt werden.

Jeder Span kann zusätzliche Attribute haben. Span-Attribute enthalten zusätzliche Metadaten wie den Sortierschlüssel der Nachricht, die Nachrichten-ID und die Größe der Nachricht.

Die Haupt-Spans für Veröffentlichung und Abo werden mit Span-Ereignissen erweitert, die dem Zeitpunkt entsprechen, an 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 von erfassten Spans in Cloud Trace wurde erreicht.
- Ihre Anwendung wird beendet, ohne die entsprechende Flush-Funktion aufzurufen.