Trace-Labels

Trace bietet einen Mechanismus, mit dem Sie Ihre Span mit aussagekräftigen Daten annotieren können. Wenn Sie die Cloud Trace API V1 verwenden, erstellen Sie diese Annotationen mithilfe des Felds labels in der Cloud Trace API TraceSpan-Objekt. Wenn Sie die Cloud Trace API V2 verwenden, können Sie Annotationen verwenden. Weitere Informationen zu Anmerkungsoptionen finden Sie unter Spans vermerken.

Die meisten Labels werden in der Tabelle Labels angezeigt, wenn die Trace-Wasserfallansicht zu sehen ist:

Seite

Labels werden auch an anderen Stellen angezeigt:

  • Im Bereich Details sind die häufigsten HTTP-Labels aufgeführt.
  • In der Tabelle Aufruf-Trace wird der Inhalt des Labels stacktrace aufgelistet. Diese Tabelle wird nur angezeigt, wenn der Span einen Stacktrace enthält.
  • In der Tabelle GKE-Container werden die kanonischen Labels für einen GKE-Container angezeigt. Jede Zeile in der Tabelle ist für ein bestimmtes Label vorgesehen. Der Wert ist ein Link, über den Sie weitere Informationen zur Ressource aufrufen können.

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.

    "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:

Label Wert
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.
Cluster Name Identifiziert den GKE-Cluster. Klicken Sie auf diesen Wert, um die Konfigurationsseite Cluster aufzurufen.
Namespace Identifiziert den Namespace. Klicken Sie auf diesen Wert, um die GKE-Seite Arbeitslasten aufzurufen.
Pod Name Identifiziert den GKE-Pod. Klicken Sie auf diesen Wert, um das Dashboard Pod-Details aufzurufen.
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 obige 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 Labels, die in der Trace-Wasserfallansicht angezeigt werden, 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 opencensus-go[0.15.0]
g.co/gce/instanceid 12345678900000000

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 Hunderte oder Tausende von benutzerdefinierten 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 OpenCensus Labels zu Ihren Trace-Spans hinzugefügt werden.

OpenCensus verwenden

Wenn Sie OpenCensus-Bibliotheken verwenden, müssen Sie den Namen des OpenCensus-Attributs verwenden. Unter Attribute finden Sie eine Tabelle mit dem Namen des OpenCensus-Attributs und dem vordefinierten Labelnamen in Cloud Trace.