Il tracciamento OpenTelemetry ti consente di identificare e tracciare la latenza di varie operazioni della libreria client Pub/Sub, come il batching, 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.
Ecco alcuni potenziali casi d'uso per il tracciamento OpenTelemetry:
- Il tuo servizio sta riscontrando una latenza di pubblicazione superiore al normale.
- Stai riscontrando un numero elevato di nuove consegne di messaggi.
- Una modifica alla funzione di callback del client dell'abbonato causa un'elaborazione più lunga 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.
- Abilita 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 al account di servizio i seguenti ruoli IAM sul tuo progetto:
-
Tutti:
Agente Cloud Trace (
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 necessarie le seguenti autorizzazioni:
-
Tutte:
cloudtrace.traces.patch
L'amministratore potrebbe anche essere in grado di concedere all'account di servizio queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
Flusso di lavoro di tracciamento OpenTelemetry
Per configurare la tracciabilità OpenTelemetry, utilizza le librerie client Pub/Sub e l'SDK OpenTelemetry. Con l'SDK, devi configurare un esportatore di traccia e un provider di traccia prima di connetterti alle librerie Pub/Sub. In alcune librerie, la configurazione di un fornitore di tracer è facoltativa.
Esportatore di tracce. L'SDK OpenTelemetry utilizza l'esportatore di tracce per determinare dove inviare le tracce.
Fornitore di tracer. Le librerie client Pub/Sub utilizzano il provider di traccia 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 tracciamento utilizzando l'SDK OpenTelemetry.
- Configura il client con l'opzione di attivazione della tracciabilità OpenTelemetry.
- Utilizza le librerie client Pub/Sub per pubblicare un messaggio.
Come funziona la 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 lo pubblichi fino a quando viene confermato. Una traccia contiene informazioni come la durata delle operazioni, gli span principali e secondari e gli span collegati.
Una traccia è composta da uno span principale e dai relativi span secondari. Questi intervalli rappresentano il lavoro svolto dalla libreria client durante l'elaborazione di un messaggio. Ogni traccia del messaggio contiene quanto segue:
- Per la pubblicazione. Controllo del flusso, pianificazione dell'ordine delle chiavi, batch e la durata della RPC di pubblicazione.
- Per gli abbonamenti. Controllo della concorrenza, pianificazione delle chiavi di ordinamento e gestione dei lease.
Per propagare le informazioni dal lato di pubblicazione a quello di iscrizione, le librerie client inseriscono un attributo specifico di tracciamento sul lato di pubblicazione. Il meccanismo di propagazione del contesto viene attivato solo quando la tracciatura è attiva e viene anteposto il prefisso googclient_
.
Pubblica messaggi con tracciamento
Il seguente esempio di codice mostra come abilitare 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 fornitore di tracer, configuri un rapporto di campionamento con l'SDK OpenTelemetry. Questo rapporto determina il numero di tracce che l'SDK deve campionare. Una frequenza di campionamento inferiore può contribuire a ridurre i costi di fatturazione e impedire che il tuo servizio superi la quota di span di Cloud Trace.
Vai
C++
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
TypeScript
Node.js
Java
Ricezione di messaggi con tracciamento
Vai
C++
Python
TypeScript
Node.js
Java
Analizzare una traccia
Le sezioni seguenti contengono informazioni dettagliate su come monitorare e analizzare una traccia nella console Google Cloud .
Considerazioni
- Quando pubblichi un batch di messaggi, lo span RPC di pubblicazione viene acquisito in una traccia separata.
- Una RPC di pubblicazione ha più intervalli di origine, poiché più chiamate di creazione possono generare una RPC di pubblicazione quando vengono raggruppate.
Gli span in OpenTelemetry possono avere zero o un solo span principale.
Gli span che rappresentano operazioni batch, ad esempio un batch di pubblicazione, (che logicamente dovrebbe avere più genitori) non possono essere rappresentati utilizzando span padre zero o uno.
Monitorare gli intervalli creati durante il ciclo di vita del messaggio
L'immagine seguente mostra un esempio di intervalli creati in una singola traccia per un singolo messaggio.
Ogni intervallo può avere attributi aggiuntivi che forniscono informazioni aggiuntive, come le dimensioni in byte del messaggio e le informazioni sulla chiave di ordinamento.
Gli attributi dello span trasmettono metadati aggiuntivi, come la chiave di ordinamento del messaggio, l'ID messaggio e le dimensioni del messaggio.
Gli intervalli di pubblicazione e iscrizione principali vengono aumentati con eventi span che corrispondono al momento in cui viene emesso un call di rete e al momento in cui viene completato.
Risolvere i problemi comuni
I seguenti problemi possono causare problemi con il tracciamento:
- Il account di servizio che utilizzi per esportare le tracce non dispone del ruolo
roles/cloudtrace.agent
richiesto. - È stata raggiunta la quota del numero massimo di span inseriti in Cloud Trace.
- L'applicazione viene terminata senza chiamare la funzione di svuotamento appropriata.