Informazioni di riferimento sull'osservabilità dei microservizi

Dati di configurazione

I dati di configurazione trovati nelle variabili di ambiente sono definiti nella seguente tabella.

Campi Specifiche
project_id Stringa

L'identificatore del progetto a cui vengono inviati i dati di osservabilità. Se è vuoto, il plug-in di osservabilità gRPC tenta di recuperare l'ID progetto dalle variabili di ambiente o dalle credenziali predefinite.

Se non lo trovi, le funzioni init di osservabilità restituiscono un errore.
cloud_logging Oggetto

Le opzioni di logging sono categorizzate in questa tabella.
Se non è presente, il logging è disabilitato.
cloud_logging.client_rpc_events[] Elenco

Un elenco di configurazioni di client_rpc_events, che rappresenta la configurazione per le RPC in uscita dal programma binario.

Le configurazioni di client_rpc_events vengono valutate in ordine di testo e viene utilizzata la prima corrispondente. Se una RPC non corrisponde a una voce, passa alla voce successiva nell'elenco.
cloud_logging.client_rpc_events[].methods[] Elenco [Stringa]

Un elenco di identificatori del metodo.

Per impostazione predefinita, l'elenco è vuoto e non corrisponde alcun metodo.

Il valore del metodo è sotto forma di [service]/[method].

* è accettato come carattere jolly per:
  • Il nome del metodo. Se il valore è [service]/*, corrisponderà a tutti i metodi nel servizio specificato.
  • Il valore intero del campo che corrisponde a qualsiasi [service]/[method]. Non è supportato quando client_rpc_events[].exclude è true.
  • Il carattere jolly * non può essere utilizzato in modo indipendente nel nome del servizio. */[method] non è supportato.

Se specificato, il nome del servizio deve essere il nome completo del servizio, incluso il nome del pacchetto.

Esempi:
  • goo.Foo/Bar seleziona solo il metodo Bar dal servizio goo.Foo, qui goo è il nome del pacchetto.
  • goo.Foo/* seleziona tutti i metodi dal servizio goo.Foo
  • * seleziona tutti i metodi da tutti i servizi.
cloud_logging.client_rpc_events[].exclude Bool

Indica se i metodi indicati da client_rpc_events[].methods[] devono essere esclusi dal logging.

Il valore predefinito è false, il che significa che i metodi indicati da client_rpc_events[].methods[] sono inclusi nel record di log.

Se il valore è true, il carattere jolly (*) non può essere utilizzato come valore intero nella colonna client_rpc_events[].methods[].
cloud_logging.client_rpc_events[].max_metadata_bytes Int

Numero massimo di byte di metadati da registrare. Se la dimensione dei metadati è maggiore del limite definito, le coppie chiave-valore che superano il limite non vengono registrate.

Il valore predefinito è 0, a indicare che non vengono registrati metadati.
cloud_logging.client_rpc_events[].max_message_bytes Int

Numero massimo di byte di ciascun messaggio da registrare. Se le dimensioni del messaggio superano il limite definito, i contenuti che superano il limite vengono troncati.

Il valore predefinito è 0, che indica che non viene registrato alcun payload di messaggi.
cloud_logging.server_rpc_events[] Elenco

Un elenco di configurazioni server_rpc_events, rappresenta la configurazione per le RPC in arrivo al programma binario.

Le configurazioni di server_rpc_events vengono valutate in ordine di testo e viene utilizzata la prima corrispondente. Se una RPC non corrisponde a una voce, passa alla voce

successiva nell'elenco.
cloud_logging.server_rpc_events[].methods[] Elenco [Stringa]

Un elenco di stringhe per cui è possibile selezionare un gruppo di metodi.

Per impostazione predefinita, l'elenco è vuoto e non corrisponde alcun metodo.

Il valore del metodo è sotto forma di [service]/[method].

* è accettato come carattere jolly per:
  • Il nome del metodo. Se il valore è [service]/*, corrisponderà a tutti i metodi nel servizio specificato.
  • Il valore intero del metodo che corrisponde a qualsiasi [service]/[method]. Non è supportato se server_rpc_events[].exclude è true.
  • Il carattere jolly * non può essere utilizzato in modo indipendente nel nome del servizio. */[method] non è supportato.

Se specificato, il nome del servizio deve essere il nome completo del servizio, incluso il nome del pacchetto.

Esempi:
  • goo.Foo/Bar seleziona solo il metodo Bar dal servizio goo.Foo, qui goo è il nome del pacchetto.
  • goo.Foo/* seleziona tutti i metodi dal servizio goo.Foo
  • * seleziona tutti i metodi da tutti i servizi.
cloud_logging.server_rpc_events[].exclude Bool

Indica se i metodi indicati da server_rpc_events[].methods[] devono essere esclusi dal logging.

Il valore predefinito è false, il che significa che i metodi indicati dall'elemento server_rpc_events[].methods[] vengono registrati.

Se il valore è true, il carattere jolly (*) non può essere utilizzato come valore intero in qualsiasi voce di server_rpc_events[].methods[].
cloud_logging.server_rpc_events[].max_metadata_bytes Int

Numero massimo di byte di metadati da registrare. Se la dimensione dei metadati è maggiore del limite definito, le coppie chiave-valore che superano il limite non vengono registrate.

Il valore predefinito è 0, a indicare che non vengono registrati metadati.
cloud_logging.server_rpc_events[].max_message_bytes Int

Numero massimo di byte di ciascun messaggio da registrare. Se le dimensioni del messaggio superano il limite definito, i contenuti che superano il limite vengono troncati.

Il valore predefinito è 0, che indica che non viene registrato alcun payload di messaggi.
cloud_monitoring Oggetto

Abilita Cloud Monitoring. Nessuna opzione di configurazione. Se fornisci un'obiezione di configurazione vuota, il monitoraggio è abilitato. Se non fornisci un oggetto di configurazione, il monitoraggio viene disabilitato.

Ad esempio, se non vengono specificate altre opzioni, una sezione di configurazione vuota abilita il monitoraggio.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace Oggetto

Una sezione di configurazione vuota consente il tracciamento con le opzioni di configurazione predefinite. Se non fornisci un oggetto di configurazione, il tracciamento è disabilitato.

Ad esempio, una sezione di configurazione vuota consente di eseguire il tracciamento con le opzioni di configurazione predefinite.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


Quando il tracciamento è abilitato, anche con una frequenza di campionamento "0", la decisione di campionare una determinata traccia viene propagata.
cloud_trace.sampling_rate Numero

L'impostazione globale che controlla la probabilità di tracciamento di una RPC. Ad esempio:
  • Il valore 0.05 indica che esiste una probabilità del 5% che una RPC venga tracciata.
  • Il valore 1.0 indica che ogni chiamata viene tracciata.
  • Il valore 0 indica di non avviare nuove tracce.

Per impostazione predefinita, il valore di campion_rate è 0.

Il plug-in rispetta la decisione di campionamento a monte. Se viene scelta una RPC per il campionamento upstream, il plug-in raccoglie gli intervalli e carica i dati nel backend, indipendentemente dall'impostazione della frequenza di campionamento per il plug-in.
labels Oggetto

Un oggetto JSON contenente un insieme di coppie chiave-valore. Sia la chiave che il valore sono stringhe.

Le etichette vengono applicate insieme a Cloud Logging, Cloud Monitoring e Cloud Trace.

Definizioni di Trace

Questa sezione fornisce informazioni sul tracciamento.

Propagazione del contesto di Trace

Affinché il tracciamento tra servizi funzioni, il proprietario del servizio deve supportare la propagazione del contesto di traccia ricevuto dall'upstream (o avviato da solo) al downstream. Il contesto Trace viene propagato tra i servizi tramite i metadati gRPC. Assicurati di abilitare le API Cloud Monitoring, Cloud Logging, Cloud Trace e le API Microservizi, che consentono ai servizi in questa configurazione di segnalare i dati di telemetria al servizio appropriato.

Senza il supporto della propagazione, i servizi downstream non possono generare intervalli per una traccia. Gli intervalli esistenti non sono interessati. I plug-in di osservabilità dei microservizi supportano il formato OpenCensus Binary Format per la codifica e la codifica del contesto delle tracce.

Intervalli

Il nome di un intervallo ha il seguente formato:

Tipo Valore di esempio Utilizzo
Intervallo RPC [Sent|Recv].helloworld.Greeter.SayHello Il nome dell'intervallo è il nome completo del metodo, collegato da punti, senza barra del prefisso.
I nomi degli intervalli sono preceduti dal prefisso Sent. per l'intervallo RPC CLIENT e Recv. per l'intervallo RPC SERVER davanti al nome completo del metodo.
Intervallo tentativi Attempt.helloworld.Greeter.SayHello Aggiunta di un prefisso Attempt. davanti al nome completo del metodo.

Etichette intervallo

Le integrazioni forniscono etichette di intervallo diverse.

Per gli intervalli di tentativi, sono allegati due attributi aggiuntivi correlati ai nuovi tentativi (etichette di intervallo):

Etichetta Valore di esempio Utilizzo
precedenti-tenta-rpc-tentativi 0 Il conteggio dei nuovi tentativi prima di questa RPC.
trasparente-riprova True/False Indica se questa RPC viene avviata da un nuovo tentativo trasparente.

Definizioni delle metriche

Le seguenti metriche sono disponibili e vengono visualizzate in una dashboard denominata Monitoraggio dei microservizi (gRPC) per i percorsi degli utenti comuni.

Di seguito sono riportate le metriche delle metriche lato client gRPC:

Nome metrica Description Tipo, tipo, unità Etichette
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs Il numero di tentativi RPC client avviati, inclusi quelli non completati. Cumulativo, Int64, 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs Il conteggio delle RPC client completate, ad esempio quando una risposta viene ricevuta o inviata dal server. Cumulativo, Int64, 1 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency Tempo end-to-end impiegato per completare un tentativo RPC, incluso il tempo necessario per scegliere un sottocanale. Cumulativa, Distribuzione, ms grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency Il tempo totale impiegato dalla libreria gRPC per completare una RPC dal punto di vista dell'applicazione. Cumulativa, Distribuzione, ms grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc Il totale dei byte (compressi, non criptati) inviati in tutti i messaggi di richiesta per tentativo RPC. Cumulativa, Distribuzione, per grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc Il totale dei byte (compressi, non criptati) ricevuti in tutti i messaggi di risposta per tentativo RPC. Cumulativa, Distribuzione, per grpc_client_method, grpc_client_status

Sono disponibili le seguenti metriche gRPC lato server:

Nome metrica Description Tipo, tipo, unità Etichette
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
Numero di RPC mai ricevute al server, incluse quelle non completate.		 Cumulativo, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
Il numero totale di RPC completate, ad esempio quando viene inviata una risposta dal server.		 Cumulativo, Int64, 1 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
I byte totali (compressi non criptati) inviati in tutti i messaggi di risposta per RPC.		 Cumulativa, Distribuzione, per grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
Il totale dei byte (compressi non criptati) ricevuti in tutti i messaggi di richiesta per RPC.		 Cumulativa, Distribuzione, per grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
Il tempo totale impiegato da una RPC dal punto di vista del trasporto dei server (HTTP2 / inproc / cronet).		 Cumulativa, Distribuzione, ms grpc_server_method

Ogni distribuzione nella tabella precedente contiene un istogramma con bucket come segue:

  • Dimensioni in byte: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268430237, 18435437, 182924

  • Latenza in ms: 0, 0,01, 0,05, 0,1, 0,3, 0,6, 0,8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65

Descrizione tag:

  • grpc_client_method: nome completo del metodo gRPC, inclusi pacchetto, servizio e metodo, ad esempio google.bigtable.v2.Bigtable/CheckAndMutateRow
  • grpc_client_status: codice di stato del server gRPC ricevuto, ad esempio OK, CANCELLED, DEADLINE_EXCEEDED
  • grpc_server_method: nome completo del metodo gRPC, inclusi pacchetto, servizio e metodo, ad esempio com.exampleapi.v4.BookshelfService/Checkout
  • grpc_server_status: codice di stato del server gRPC restituito, ad esempio OK, CANCELLED, DEADLINE_EXCEEDED

Definizioni dei record di log

I log di osservabilità dei microservizi vengono caricati in Cloud Logging utilizzando il nome del log (PROJECT_ID è il segnaposto per la stringa che rappresenta il tuo progetto):

logName=projects/[PROJECT_ID]/logs/microservices.googleapis.com%2Fobservability%2Fgrpc

Di seguito è riportata la rappresentazione JSON del record di log generato:

{
    "authority": string,
    "callId": string,
    "type": string,
    "logger": string,
    "serviceName": string,
    "methodName": string,
    "peer": {
        "type": string,
        "address": string,
        "ipPort": int
    },
    "payload": {
        "timeout": string,
        "metadata":
            {
                string: string,
                string: string
            },
        "statusCode": string,
        "statusMessage": string,
        "statusDetails": string,
        "message": string,
        "messageLength": int,
    },
    "sequenceId": int
}

Nella tabella seguente vengono descritti i campi della voce di log:

Campi Specifiche
autorità Stringa

È possibile utilizzare un singolo processo per eseguire più server virtuali con identità diverse.

Per autorità si intende il nome di questa identità server. Solitamente è una porzione dell'URI nel formato host oppure host:porta.
callId Stringa

Identifica in modo univoco una chiamata [client/server] che è un UUID. Ogni chiamata può avere diverse voci di log. Hanno tutti lo stesso ID chiamata.
tipo Stringa

Il tipo di evento del log.

I tipi di evento sono:
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
logger Stringa

Il tipo di logger eventi.

I tipi di log di eventi sono:
LOGGER_UNKNOWN, CLIENT e SERVER
serviceName Stringa

Il nome del servizio.
methodName Stringa

Il nome del metodo RPC.
collega Oggetto

Informazioni sull'indirizzo del peer. Sul lato client, il peer è registrato sugli eventi di intestazione server ed eventi trailer. Sul lato server, il peer viene sempre registrato sull'evento di intestazione del client.
peer.type Stringa

Il tipo di indirizzo, che sia IPv4, IPv6 o UNIX.
peer.address Stringa

Il contenuto dell'indirizzo.
peer.ip_port Int

Il numero di porta dell'indirizzo. Disponibile solo per gli indirizzi IPv4 e IPv6.
payload Oggetto

Il payload può includere una combinazione di metadati, timeout, messaggio e stato a seconda dell'evento.

  • Per gli eventi di messaggio, il payload è costituito dai dati effettivi passati come messaggi client/server e dalla lunghezza del messaggio.
  • Per gli eventi di intestazione, il payload include il nome e il valore dell'intestazione.
  • Per gli eventi trailer, il payload include dettagli sullo stato e i metadati del trailer (se presenti).
  • Per gli eventi dell'intestazione client, se è impostato un timeout, il payload include anche questo timeout.
payload.timeout Stringa

Una stringa che rappresenta google.protobuf.Duration, ad esempio "1,2 s".

Il valore di timeout RPC.
payload.metadata Mapping[String, String]

Utilizzato dall'evento di intestazione o dall'evento trailer.
payload.message Stringa (byte)

Il payload del messaggio.
payload.messageLength Int

Dimensioni del messaggio, indipendentemente dal fatto che l'intero messaggio venga registrato (ad esempio, potrebbe essere troncato oppure omesso).
payload.statusCode Stringa

Il codice di stato gRPC.
payload.statusMessage Stringa

Il messaggio di stato gRPC.
payload.statusDetails Stringa

Il valore dell'eventuale chiave di metadati grpc-status-details-bin. Si tratta sempre di un messaggio google.rpc.Status codificato.
payloadTruncated Bool

True se il campo del messaggio o dei metadati viene troncato o omesso a causa delle opzioni di configurazione.
sequenceId Int

L'ID sequenza di messaggi per questa chiamata. Il primo messaggio ha un valore 1 per distinguerlo da un valore non impostato. Lo scopo di questo campo è rilevare le voci mancanti negli ambienti in cui la durabilità o l'ordinamento non sono garantiti.

Etichette risorse

Le etichette delle risorse identificano l'origine che genera dati di osservabilità. Ogni etichetta delle risorse è una coppia chiave-valore in cui le chiavi sono valori predefiniti specifici dell'ambiente di origine (ad esempio GKE o Compute Engine).

Per le metriche e il tracciamento sui deployment GKE, le etichette delle risorse vengono compilate per impostazione predefinita, ad eccezione del nome del container e del nome dello spazio dei nomi. I valori mancanti possono essere compilati utilizzando l'API Downward.

Di seguito sono riportate le chiavi variabile di ambiente:

  • CONTAINER_NAME
  • NAMESPACE

Ad esempio, la sezione env di seguito include due etichette delle risorse:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: app1
  name: app1
spec:
  replicas: 2
  selector:
    matchLabels:
      run: app1
  template:
    metadata:
      labels:
        run: app1
    spec:
      containers:
        - image: 'o11y-examples:1.00'
          name: container1
          ports:
            - protocol: TCP
              containerPort: 50051
          env:
            - name: CONTAINER_NAME
              value: container1
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

Etichette personalizzate

Le etichette personalizzate rappresentano informazioni aggiuntive fornite dall'utente nei dati di osservabilità. Le etichette sono composte da una chiave e un valore. La coppia chiave-valore è associata al tracciamento dei dati come etichette di intervallo, ai dati delle metriche come etichette delle metriche e al logging dei dati come etichette voce di log. Tutte le etichette personalizzate sono di tipo STRING.

Puoi fornire etichette personalizzate nella configurazione specificando un elenco di coppie chiave-valore per labels. L'implementazione legge la configurazione e crea un'etichetta separata per ogni coppia chiave-valore, quindi assegna l'etichetta ai dati di osservabilità. Ad esempio:

"labels": {
    "DATACENTER": "SAN_JOSE_DC",
    "APP_ID": "24512"
  }

Ogni voce di log contiene le seguenti etichette aggiuntive:

{
   "DATACENTER": "SAN_JOSE_DC"
   "APP_ID": "24512"
}

Passaggi successivi