La tracciabilità di OpenTelemetry consente di identificare e tracciare la latenza di varie operazioni della libreria client Pub/Sub, come l'elaborazione in batch, la gestione dei lease e il controllo del flusso. La raccolta di queste informazioni può aiutarti a eseguire il debug dei problemi della libreria client.
Alcuni potenziali casi d'uso per la tracciabilità di OpenTelemetry includono:
- Il tuo servizio sta riscontrando una latenza di pubblicazione superiore al normale.
- Stai riscontrando un numero elevato di riconsegne dei messaggi.
- Una modifica alla funzione di callback del client dell'abbonato fa sì che l'elaborazione richieda più tempo del solito.
Prima di iniziare
Prima di configurare OpenTelemetry, completa le seguenti attività:
- Configura Pub/Sub utilizzando una delle librerie client.
- Installa l'SDK OpenTelemetry e configura un esportatore di tracce e un provider di tracer.
- Attiva l'API Cloud Trace.
- Scopri come leggere le tracce di Cloud Observability.
Ruoli obbligatori
Per assicurarti che il account di servizio disponga delle autorizzazioni necessarie per esportare le tracce in Cloud Trace, chiedi all'amministratore di concedere i seguenti ruoli IAM al account di servizio sul tuo progetto:
-
Tutti:
Cloud Trace Agent (
roles/cloudtrace.agent)
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Questi ruoli predefiniti contengono le autorizzazioni necessarie per esportare le tracce in Cloud Trace. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per esportare le tracce in Cloud Trace sono richieste le seguenti autorizzazioni:
-
Tutti:
cloudtrace.traces.patch
L'amministratore potrebbe anche essere in grado di concedere al account di servizio queste autorizzazioni tramite ruoli personalizzati o altri ruoli predefiniti.
Flusso di lavoro della tracciabilità di OpenTelemetry
Per configurare la tracciabilità di OpenTelemetry, utilizza le librerie client Pub/Sub e l'SDK OpenTelemetry. Con l'SDK, devi configurare un esportatore di tracce e un provider di tracer prima di connetterti alle librerie Pub/Sub. In alcune librerie, la configurazione di un provider di tracer è facoltativa.
Esportatore di tracce. L'SDK OpenTelemetry utilizza l'esportatore di tracce per determinare dove inviare le tracce.
Provider di tracer. Le librerie client Pub/Sub utilizzano il provider di tracer per creare le tracce.
I seguenti passaggi descrivono come configurare la tracciabilità:
- Crea un'istanza di un esportatore OpenTelemetry di Cloud Trace.
- Se necessario, crea un'istanza e registra un provider di tracer utilizzando l'SDK OpenTelemetry.
- Configura il client con l'opzione per attivare la tracciabilità di OpenTelemetry.
- Utilizza le librerie client Pub/Sub per pubblicare un messaggio.
Funzionamento della tracciabilità
Per ogni messaggio pubblicato, la libreria client crea una nuova traccia. Questa traccia rappresenta l'intero ciclo di vita del messaggio, dal momento in cui pubblichi un messaggio fino a quando il messaggio non viene riconosciuto. Una traccia incapsula informazioni come la durata delle operazioni, gli intervalli principali e secondari e gli intervalli collegati.
Una traccia è composta da un intervallo principale e dai relativi intervalli secondari. Questi intervalli rappresentano il lavoro svolto dalla libreria client durante l'elaborazione di un messaggio. Ogni traccia di messaggio contiene quanto segue:
- Per la pubblicazione. Controllo del flusso, pianificazione della chiave di ordinamento, elaborazione in batch e durata della RPC di pubblicazione.
- Per gli abbonamenti. Controllo della concorrenza, pianificazione della chiave di ordinamento e gestione dei lease.
Per propagare le informazioni dal lato di pubblicazione a quello di abbonamento, le librerie client inseriscono un attributo specifico di tracciabilità sul lato di pubblicazione. Il meccanismo di propagazione del contesto è abilitato solo quando la tracciabilità è attiva e viene anteposto al prefisso googclient_.
Pubblicare messaggi con la tracciabilità
Il seguente esempio di codice mostra come attivare la tracciabilità utilizzando la libreria client Pub/Sub e l'SDK OpenTelemetry. In questo esempio, i risultati della tracciabilità vengono esportati in Cloud Trace.
Considerazioni
Quando crei un'istanza del provider di tracer, configuri una frequenza di campionamento con l'SDK OpenTelemetry. Questa frequenza determina il numero di tracce che l'SDK deve campionare. Una frequenza di campionamento inferiore può contribuire a ridurre i costi di fatturazione e a impedire a l servizio di superare la quota di intervalli di Cloud Trace.
Vai
C++
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Python di Pub/Sub.