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 im Cloud Trace API-Objekt TraceSpan. Wenn Sie die Cloud Trace API V2 verwenden, können Sie mit Attributen annotieren. Weitere Informationen zu Annotationsoptionen finden Sie unter Spans annotieren.

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

Seite

Es gibt zwei weitere Stellen, an denen Labels angezeigt werden. Im Bereich Details werden die gebräuchlichsten HTTP-Labels aufgeführt, in der Tabelle Aufruf-Trace wird der Inhalt des Labels stacktrace aufgeführt.

Das Feld labels ist eine Zuordnung von Schlüssel/Wert-Paaren. Diese Schlüssel und Werte werden als Strings gespeichert. Informationen zu Längenbeschränkungen für Strings finden Sie in der API-Referenz zu labels.

Pro Span sind maximal 32 Labels zulässig.

Vordefinierte Schlüssel

In der folgenden Tabelle sind die unterstützten vordefinierten Schlüssel mit einer Beschreibung und in einigen Fällen mit einem Beispiel aufgeführt:

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.
Verwenden Sie diesen Schlüssel nicht für Nicht-HTTP-Anfragen.
"GET"
/http/path Anforderungs-URL-Pfad.
"/cart/checkout"
/http/redirected_url Die URL vor der Weiterleitung.
Verwenden Sie in diesem Fall das Schlüssel-HTTL-URL-Label, um die endgültige 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 JSON-formatierter Stacktrace. Stacktraces werden für die Suche nicht 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.

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 stammt von einem System mit einem Zipkin-Collector. 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 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. Eine Tabelle, in der der OpenCensus-Attributname mit dem vordefinierten Cloud Trace-Labelnamen verknüpft ist, finden Sie unter Attribute.