Trace-Labels

Mit Labels und Attributen in Cloud Trace können Sie Schlüssel/Wert-Metadaten wie HTTP-Statuscodes, Regionsnamen oder benutzerdefinierte Anwendungseigenschaften an Ihre Spans anhängen, um Anfragen zu filtern, zu gruppieren und Fehler zu beheben. Wenn Sie die Cloud Trace API v1 verwenden, fügen Sie Schlüssel/Wert-Paare mit dem Feld labels im Objekt TraceSpan hinzu. Wenn Sie die Trace API v2 verwenden, fügen Sie Metadaten mit einem Attributes-Objekt hinzu.

Labels und Attribute

Das Feld labels ist eine Zuordnung von Schlüssel/Wert-Paaren, die als Strings gespeichert werden. Es gilt ein Limit von 1.024 Labels pro Span. Informationen zu Einschränkungen der Stringlänge finden Sie in der API-Referenz zu labels.

Wenn Sie einen Span auf der Seite Trace Explorer untersuchen, werden die Labels für diesen Span auf dem Tab Attribute angezeigt, wie im folgenden Screenshot zu sehen ist:

Beispiel für die Attributtabelle von Cloud Trace.

Informationen zum Zugriff auf diese Informationen finden Sie unter Traces finden und ansehen.

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 Label „HTTP-URL“ zum Speichern der finalen URL.
/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† Statuscode der HTTP-Antwort.
"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 in der Google Cloud Console zum GKE-Dashboard zu gelangen.
Standort
g.co/r/k8s_container/location		 Der physische Standort des GKE-Cluster.
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 stammt von einem System, in dem ein Zipkin-Collector verwendet wird. In diesem Fall wurden die Labels mit zipkin.io-Schlüsseln von diesem Collector hinzugefügt.

Präfix g.co

In einigen 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 Beispiel dargestellt, können mit einem Zipkin-Collector oder einer Bibliothek wie OpenTelemetry Labels zu Ihren Trace-Spans hinzugefügt werden.

OpenTelemetry verwenden

Wenn Sie OpenTelemetry-Bibliotheken verwenden, achten Sie darauf, dass Sie beim Erstellen von Spans die OpenTelemetry Semantic Conventions verwenden.