Trace-Labels

Trace bietet einen Mechanismus, mit dem Sie Ihren Span aussagekräftige Daten hinzufügen können. Wenn Sie die Cloud Trace API V1 verwenden, können Sie Labels (Schlüssel/Wert-Paare) mithilfe des Felds labels im Cloud Trace API-Objekt TraceSpan hinzufügen. Wenn Sie die Cloud Trace API V2 verwenden, können Sie Informationen mit einem Attributes-Objekt hinzufügen.

Wenn Sie einen Span untersuchen, werden auf dem Tab Attribute Labels für diesen Span angezeigt. Der folgende Screenshot zeigt beispielsweise diesen Tab:

Beispiel für die Cloud Trace-Attributtabelle

Informationen zum Zugriff auf diese Informationen finden Sie unter Traces suchen und untersuchen.

Das Feld labels ist eine Zuordnung von Schlüssel/Wert-Paaren. Ihre Schlüssel und Werte werden als Strings gespeichert. Informationen zur Beschränkung der Stringlänge finden Sie in der API-Referenz zu labels.

Pro Span sind maximal 32 Labels zulässig.

Vordefinierte Schlüssel

Kanonische Labels

In der folgenden Tabelle sind die unterstützten vordefinierten Schlüssel aufgelistet, eine Beschreibung und in einigen Fällen ein Beispiel:

LabelschlüsselBeschreibung
Beispiel
/agent Trace-Agent-ID.
"node@google-cloud/trace-agent v3.0.0"
/component Komponenten-ID.
"grpc"
/error/message Eine Fehlermeldung.
"Rendezvous of RPC that terminated with:
status = StatusCode.UNAVAILABLE details = OS Error."
/error/name Anzeigename für den Fehler.
/http/client_city Die Stadt des Clients.
"NYC"
/http/client_country Das Land des Clients.
"US"
/http/client_protocol HTTP-Protokoll-ID.
"1.0"
/http/client_region Die Region des Clients.
"us-east4"
/http/host Der Wert des Host Headers.
"default.example.com"
/http/method† Auf die HTTP-Anfragemethode festgelegt.
Geben Sie diesen Schlüssel nicht für Nicht-HTTP-Anfragen an.
"GET"
/http/path† Anforderungs-URL-Pfad.
"/cart/checkout"
/http/redirected_url URL vor der Weiterleitung
Verwenden Sie in diesem Fall das Schlüssel-HTTL-Label der URL, um die finale URL zu speichern.
/http/request/size Anzahl der Byte in der Anfrage
/http/response/size Anzahl der Byte in der Antwort
/http/route† Die übereinstimmende Route.
"/cart/checkout/:item_id"
/http/status_code† HTTP-Antwortstatuscode.
"200"
/http/url Vollständige HTTP-Anfrage-URL.
"http://example.com"
/http/user_agent Informationen zum HTTP-User-Agent, von dem die Anfrage stammt.
"python-requests/2.19.1"
/stacktrace Stacktrace im JSON-Format Stacktraces werden nicht für die Suche indexiert.
Dieses Label wird in der Tabelle Aufrufstack angezeigt.
Das Label /stacktrace wird nur von der V1 API verwendet.
Für die V2 API enthält span ein stackTrace-Feld. 
    "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"
          }
        ]
      }
    },

†Dieses Label und sein Wert werden in der Tabelle Details angezeigt, die in der Ansicht Trace-Details enthalten ist.

Kanonische Labels für GKE

In der folgenden Tabelle sind alle kanonischen Labels für einen GKE-Container aufgeführt:

Anzeigename in der Tabelle GKE-Container
Labelschlüssel		 Beschreibung
Projekt-ID
g.co/r/k8s_container/project_id		 Das Google Cloud Projekt, in dem der GKE-Cluster gehostet wird. Klicken Sie auf den Projektnamen, um zum GKE-Dashboard in der Google Cloud Console zu wechseln.
Standort
g.co/r/k8s_container/location		 Der physische Standort des GKE-Clusters.
Clustername
g.co/r/k8s_container/cluster_name 		Identifiziert den GKE-Cluster. Klicken Sie auf diesen Wert, um die Konfigurationsseite Cluster aufzurufen.
Namespace
g.co/r/k8s_container/namespace 		Identifiziert den Namespace. Klicken Sie auf diesen Wert, um die GKE-Seite Arbeitslasten aufzurufen.
Pod-Name
g.co/r/k8s_container/pod_name 		Identifiziert den GKE-Pod. Klicken Sie auf diesen Wert, um das Dashboard Pod-Details aufzurufen.
Containername
g.co/r/k8s_container/container_name 		Identifiziert den GKE-Container. Klicken Sie auf diesen Wert, um die Detailseite für den Container aufzurufen.

Beispiel

Im Folgenden finden Sie eine teilweise JSON-Darstellung eines Trace-Objekts mit mehreren Labels:

{
  "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"
      }
    }
  ]
}

Der vorherige Trace wurde mithilfe eines Zipkin-Collectors aus einem System übernommen. In diesem Fall wurden die Labels mit zipkin.io-Schlüsseln von diesem Collector hinzugefügt.

Präfix g.co

In manchen Fällen enthalten die angezeigten Labels das Präfix g.co. Das Präfix g.co gibt an, dass dieses Label von einem Google-Dienst generiert wurde. Wenn Sie Ihren Dienst in App Engine oder einer anderen Google Cloud Infrastruktur ausführen, werden möglicherweise Labels wie die folgenden angezeigt:

Labelschlüssel Beispiel für einen Labelwert
g.co/agent opentelemetry-js 1.18.1; google-cloud-trace-exporter 2.1.0
g.co/r/generic_node/location global

Benutzerdefinierte Labels

Sie können benutzerdefinierte Labels erstellen. Wenn Sie ein benutzerdefiniertes Label erstellen, empfehlen wir die Verwendung der folgenden Formate:

  • /category/product/key für Agents bekannter Produkte. Beispiel: /db/mongodb/read_size
  • short_host/path/key für domainspezifische Schlüssel. Beispiel: g.co/agent

Wenn Sie viele benutzerdefinierte Labels erstellen, kann dies aufgrund der höheren Labelkardinalität zu Leistungseinbußen führen.

Wie im Abschnitt Beispiel dargestellt, können bei Verwendung eines Zipkin-Collectors oder einer Bibliothek wie OpenTelemetry Labels zu Ihren Trace-Spans hinzugefügt werden.

OpenTelemetry verwenden

Wenn Sie OpenTelemetry-Bibliotheken verwenden, müssen Sie beim Erstellen von Spans die OpenTelemetry-semantischen Konventionen einhalten.