Etichette di Trace

La funzionalità di monitoraggio fornisce un meccanismo per aggiungere dati significativi agli intervalli. Se utilizzi la versione 1 dell'API Cloud Trace, puoi aggiungere etichette, ovvero coppie chiave-valore, utilizzando il campo labels nell'objetto TraceSpan dell'API Cloud Trace. Se utilizzi l'Cloud Trace API V2, puoi aggiungere informazioni con un oggetto Attributes. Per ulteriori informazioni, vedi Aggiungi annotazioni di eventi agli intervalli di traccia.

Quando esamini un intervallo, le relative etichette vengono visualizzate nella scheda Attributi. Ad esempio, lo screenshot seguente mostra questa scheda:

Esempio della tabella degli attributi di Cloud Trace.

Per informazioni su come accedere a queste informazioni, consulta Trovare ed esplorare le tracce.

Il campo labels è una mappa di coppie chiave/valore. Le chiavi e i valori vengono memorizzati come stringhe. Per le limitazioni della lunghezza della stringa, consulta il riferimento all'API per labels.

Esiste un limite di 32 etichette per intervallo.

Chiavi predefinite

Etichette canoniche

La tabella seguente elenca le chiavi predefinite supportate, include una descrizione e, in alcuni casi, un esempio:

Chiave di etichettaEsempio
di descrizione
/agent Identificatore dell'agente di Trace.
"node@google-cloud/trace-agent v3.0.0"
/component Identificatore del componente.
"grpc"
/error/message Viene visualizzato un messaggio di errore.
"Rendezvous of RPC that terminated with:
status = StatusCode.UNAVAILABLE details = OS Error."
/error/name Il nome visualizzato per l'errore.
/http/client_city La città del cliente.
"NYC"
/http/client_country Il paese del cliente.
"US"
/http/client_protocol Identificatore del protocollo HTTP.
"1.0"
/http/client_region La regione del client.
"us-east4"
/http/host Il valore dell'intestazione Host.
"default.example.com"
/http/method† Impostato sul metodo di richiesta HTTP.
Non includere questa chiave per le richieste non HTTP.
"GET"
/http/path† Percorso dell'URL richiesta.
"/cart/checkout"
/http/redirected_url L'URL prima del reindirizzamento.
In questo caso, utilizza l'etichetta URL HTTL chiave per memorizzare l'URL finale.
/http/request/size Numero di byte nella richiesta.
/http/response/size Numero di byte nella risposta.
/http/route† Il percorso corrispondente.
"/cart/checkout/:item_id"
/http/status_code† Codice di stato risposta HTTP.
"200"
/http/url URL di richiesta HTTP completa.
"http://example.com"
/http/user_agent Informazioni sulla User-agent HTTP che ha originato la richiesta.
"python-requests/2.19.1"
/stacktrace La traccia dello stack in formato JSON. Le analisi dello stack non vengono indicizzate per la ricerca.
Questa etichetta viene visualizzata nella tabella Call Stack.
L'etichetta /stacktrace viene utilizzata solo dall'API V1.
Per l'API V2, span contiene un campo stackTrace. 
    "stackTrace": {
      "stackFrames": {
        "frame": [
          {
            "functionName": {
              "value": "serverMethodTrace [as func]"
            },
            "fileName": {
              "value":
              "/usr/src/app/node_modules/@google-cloud/trace-agent/build/src/plugins/plugin-grpc.js"
            },
            "lineNumber": "249",
            "columnNumber": "28"
          },
          {
            "functionName": {
              "value": "anonymous function"
            },
            "fileName": {
              "value": "/usr/src/app/node_modules/grpc/src/server.js"
            },
            "lineNumber": "592",
            "columnNumber": "13"
          }
        ]
      }
    },

†Questa etichetta e il relativo valore vengono visualizzati nella tabella Dettagli inclusa nella visualizzazione Dettagli traccia.

Etichette canoniche per GKE

La tabella seguente elenca tutte le etichette canonical per un contenitore GKE:

Nome visualizzato nella tabella Container GKE
Chiave di etichetta		 Descrizione
ID progetto
g.co/r/k8s_container/project_id		 Il progetto Google Cloud che ospita il cluster GKE. Fai clic sul nome del progetto per andare dashboard di GKE nella console Google Cloud.
Località
g.co/r/k8s_container/location		 La località fisica del cluster GKE.
Nome del cluster
g.co/r/k8s_container/cluster_name 		Identifica il cluster GKE. Per accedere alla sezione Cluster, fai clic su questo valore.
Spazio dei nomi
g.co/r/k8s_container/namespace 		Identifica lo spazio dei nomi. Per accedere alla sezione Nella pagina Carichi di lavoro di GKE, fai clic su questo valore.
Nome del pod
g.co/r/k8s_container/pod_name 		Identifica il pod GKE. Per andare alla dashboard Dettagli dei pod, fai clic su questo valore.
Nome contenitore
g.co/r/k8s_container/container_name 		Identifica il container GKE. Per andare alla pagina dei dettagli del contenitore, fai clic su questo valore.

Esempio

Di seguito è riportata una rappresentazione JSON parziale di un oggetto Trace che include più etichette:

{
  "projectId": "a-sample-project",
  "traceId": "00000000000000004db6dd68e7d37f57",
  "spans": [
    {
      "spanId": "12913864118554233534",
      "kind": "RPC_SERVER",
      "name": "http://xx.xxx.xxx.xxx/",
      "startTime": "2019-04-02T19:37:34.149058Z",
      "endTime": "2019-04-02T19:37:34.151136Z",
      "parentSpanId": "5599906629317525335",
      "labels": {
        "/component": "default",
        "/http/host": "xx.xxx.xxx.xxx",
        "/http/status_code": "200",
        "/http/url": "http://xx.xxx.xxx.xxx/",
        "zipkin.io/http.route": "/**",
        "/http/method": "GET",
        "zipkin.io/endpoint.ipv4": "10.16.1.6",
        "zipkin.io/http.path": "/",
        "zipkin.io/mvc.controller.class": "ResourceHttpRequestHandler"
      }
    }
  ]
}

La traccia precedente è stata acquisita da un sistema che utilizza un raccoglitore Zipkin. In questo caso, le etichette con zipkin.io chiavi sono state aggiunte dal raccoglitore.

Prefisso g.co

In alcuni casi, le etichette visualizzate contengono un prefisso g.co. Il prefisso g.co indica che questa etichetta è stata generata da un servizio Google. Se esegui il tuo servizio su App Engine o su un'altra infrastruttura Google Cloud, potresti visualizzare etichette come le seguenti:

Chiave di etichetta Valore dell'etichetta di esempio
g.co/agent opentelemetry-js 1.18.1; google-cloud-trace-exporter 2.1.0
g.co/r/generic_node/location global

Etichette personalizzate

Puoi creare etichette personalizzate. Se crei un'etichetta personalizzata, ti consigliamo che utilizzi i seguenti formati:

  • /category/product/key per gli agenti di prodotti ben noti. Ad esempio, /db/mongodb/read_size.
  • short_host/path/key per le chiavi specifiche del dominio. Ad esempio, g.co/agent.

Se crei molte etichette personalizzate, potresti riscontrare un calo delle prestazioni a causa dell'aumento della cardinalità delle etichette.

Come illustrato nella sezione Esempio, se utilizzi un raccoltore Zipkin o una libreria come OpenTelemetry, potresti aggiungere etichette agli intervalli di traccia.

Utilizzo di OpenTelemetry

Se utilizzi librerie OpenTelemetry, assicurati di usare il parametro Convenzioni semantiche di OpenTelemetry durante la creazione di intervalli.