Trace-Labels

Trace bietet einen Mechanismus, mit dem Sie Ihren Spans aussagekräftige Daten hinzufügen können. Wenn Sie die Cloud Trace API V1 verwenden, können Sie Labels, bei denen es sich um Schlüssel/Wert-Paare handelt, mithilfe des Felds labels im Objekt der Cloud Trace API TraceSpan hinzufügen. Wenn Sie die Cloud Trace API V2 verwenden, können Sie Informationen mithilfe eines Attributes-Objekts hinzufügen. Weitere Informationen finden Sie unter Ereignisanmerkungen zu Trace-Spans hinzufügen.

Wenn Sie einen Span untersuchen, werden seine Labels auf dem Tab Attribute angezeigt. Der folgende Screenshot zeigt diese Registerkarte beispielsweise:

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 Komponentenkennung.
"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 Kunden.
"NYC"
/http/client_country Das Land des Kunden.
"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† Pfad der Anfrage-URL.
"/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† 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 das GKE-Dashboard in der Google Cloud Console aufzurufen.
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://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"
      }
    }
  ]
}

Der vorherige Trace wurde von einem System mit einem Zipkin-Collector abgerufen. 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.

Wenn Sie einen Zipkin-Collector oder eine Bibliothek wie OpenTelemetry verwenden, wie im Beispiel-Abschnitt dargestellt, werden Ihren Trace-Spans möglicherweise Labels hinzugefügt.

OpenTelemetry verwenden

Wenn Sie OpenTelemetry-Bibliotheken verwenden, müssen Sie beim Erstellen von Spans die OpenTelemetry Semantic Conventions (Semantische Konventionen von OpenTelemetry) verwenden.