Etichette di Trace

Le etichette e gli attributi in Cloud Trace ti consentono di collegare metadati coppia chiave-valore, come codici di stato HTTP, nomi di regioni o proprietà di applicazioni personalizzate, agli span in modo da poter filtrare, raggruppare e risolvere i problemi relativi alle richieste. Se utilizzi l'Cloud Trace API v1, aggiungi le coppie chiave/valore utilizzando il campo labels nell'oggetto TraceSpan. Se utilizzi l'API Trace v2, aggiungi i metadati utilizzando un oggetto Attributes.

Informazioni su etichette e attributi

Il campo labels è una mappa di coppie chiave-valore memorizzate come stringhe, con un limite di 1024 etichette per intervallo. Per le limitazioni della lunghezza delle stringhe, consulta il Riferimento API per labels.

Quando esplori uno span nella pagina Esplora tracce, le etichette per questo span vengono visualizzate nella scheda Attributi, come mostrato nello screenshot seguente:

Esempio della tabella degli attributi di Cloud Trace.

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

Chiavi predefinite

Etichette canoniche

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

Chiave di etichettaDescrizione
Esempio
/agent Identificatore dell'agente di Trace.
"node@google-cloud/trace-agent v3.0.0"
/component Identificatore del componente.
"grpc"
/error/message Un messaggio di errore.
"Rendezvous of RPC that terminated with:
status = StatusCode.UNAVAILABLE details = OS Error."
/error/name 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 cliente.
"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 della richiesta.
"/cart/checkout"
/http/redirected_url L'URL prima del reindirizzamento.
In questo caso, utilizza l'etichetta URL HTTP chiave per memorizzare l'URL finale.
/http/request/size Numero di byte nella richiesta.
/http/response/size Numero di byte nella risposta.
/http/route† La route corrispondente.
"/cart/checkout/:item_id"
/http/status_code† Codice di stato della risposta HTTP.
"200"
/http/url URL della richiesta HTTP completa.
"http://example.com"
/http/user_agent Informazioni sullo user agent HTTP che ha generato la richiesta.
"python-requests/2.19.1"
/stacktrace Analisi 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 canoniche per un container 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 alla dashboard GKE nella console Google Cloud .
Località
g.co/r/k8s_container/location		 La posizione fisica del cluster GKE.
Nome del cluster
g.co/r/k8s_container/cluster_name 		Identifica il cluster GKE. Per andare alla pagina di configurazione Cluster, fai clic su questo valore.
Spazio dei nomi
g.co/r/k8s_container/namespace 		Identifica lo spazio dei nomi. Per andare alla pagina Workload di GKE, fai clic su questo valore.
Nome pod
g.co/r/k8s_container/pod_name 		Identifica il pod GKE. Per andare alla dashboard Dettagli 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 container, 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://192.0.2.0/",
      "startTime": "2024-04-02T19:37:34.149058Z",
      "endTime": "2025-04-02T19:37:34.151136Z",
      "parentSpanId": "5599906629317525335",
      "labels": {
        "/component": "default",
        "/http/host": "192.0.2.0",
        "/http/status_code": "200",
        "/http/url": "http://192.0.2.0/",
        "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 estratta da un sistema che utilizza un raccoglitore Zipkin. In questo caso, le etichette con chiavi zipkin.io sono state aggiunte da questo raccoglitore.

Prefisso g.co

In alcuni casi, le etichette visualizzate contengono il 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 Google Cloud infrastruttura, potresti visualizzare etichette come le seguenti:

Chiave di etichetta Valore 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 di utilizzare i seguenti formati:

  • /category/product/key per gli agenti di prodotti 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 impatto sulle prestazioni a causa dell'aumento della cardinalità delle etichette.

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

Utilizzo di OpenTelemetry

Se utilizzi le librerie OpenTelemetry, assicurati di utilizzare le convenzioni semantiche di OpenTelemetry durante la creazione degli span.