Étiquettes Trace

Trace fournit un mécanisme vous permettant d'ajouter des données pertinentes à vos segments. Si vous utilisez la version 1 de l'API Cloud Trace, vous pouvez ajouter des étiquettes, qui sont des paires clé/valeur, à l'aide du champ labels de l'objet TraceSpan de l'API Cloud Trace. Si vous utilisez l'API Cloud Trace V2, vous pouvez ajouter des informations à l'aide d'un objet Attributes. Pour en savoir plus, consultez la section Ajouter des annotations d'événement aux délais de trace.

Lorsque vous explorez un segment, ses libellés s'affichent dans l'onglet Attributs. Par exemple, la capture d'écran suivante illustre cet onglet:

Exemple de tableau d'attributs Cloud Trace

Pour savoir comment accéder à ces informations, consultez Rechercher et explorer des traces.

Le champ labels est une carte de paires clé/valeur. Ces clés et ces valeurs sont stockées sous forme de chaînes. Pour connaître les restrictions de longueur des chaînes, consultez la documentation de référence de l'API pour labels.

Le nombre de libellés par délai est limité à 32.

Clés prédéfinies

Libellés canoniques

Le tableau suivant répertorie les clés prédéfinies acceptées, inclut une description et, dans certains cas, inclut un exemple :

Clé d'étiquetteDescription
Exemple
/agent Identifiant d'agent Trace.
"node@google-cloud/trace-agent v3.0.0"
/component Identifiant du composant.
"grpc"
/error/message Un message d'erreur s'affiche.
"Rendezvous of RPC that terminated with:
status = StatusCode.UNAVAILABLE details = OS Error."
/error/name Nom à afficher pour l'erreur.
/http/client_city Ville du client.
"NYC"
/http/client_country Pays du client.
"US"
/http/client_protocol Identifiant de protocole HTTP.
"1.0"
/http/client_region Région du client.
"us-east4"
/http/host Valeur de l'en-tête de l'hôte.
"default.example.com"
/http/method† Défini sur la méthode de requête HTTP.
N'incluez pas cette clé pour les requêtes non HTTP.
"GET"
/http/path† Chemin de l'URL de requête.
"/cart/checkout"
/http/redirected_url URL avant redirection.
Dans ce cas, utilisez le libellé d'URL HTTL de clé pour stocker l'URL finale.
/http/request/size Nombre d'octets dans la requête.
/http/response/size Nombre d'octets dans la réponse.
/http/route† Route correspondante.
"/cart/checkout/:item_id"
/http/status_code† Code d'état de la réponse HTTP
"200"
/http/url URL de requête HTTP complète.
"http://example.com"
/http/user_agent Informations sur l'user-agent HTTP à l'origine de la requête.
"python-requests/2.19.1"
/stacktrace Trace de pile au format JSON. Les traces de pile ne sont pas indexées pour la recherche.
Ce libellé s'affiche dans la table Pile d'appel.
Le libellé /stacktrace n'est utilisé que par l'API V1.
Pour l'API V2, span contient un champ stackTrace. 

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

†Ce libellé et sa valeur s'affichent dans la table Details (Détails) incluse dans la vue Trace details (Détails des traces).

Libellés canoniques pour GKE

Le tableau suivant répertorie tous les libellés canoniques pour un conteneur GKE :

Nom à afficher dans la table Conteneur GKE
Clé de libellé		 Description
ID du projet
g.co/r/k8s_container/project_id		 Projet Google Cloud hébergeant le cluster GKE. Cliquez sur le nom du projet pour accéder au tableau de bord GKE dans la console Google Cloud.
Zone géographique
g.co/r/k8s_container/location		 Emplacement physique du cluster GKE.
Nom du cluster
g.co/r/k8s_container/cluster_name 		Identifie le cluster GKE. Pour accéder à la page de configuration Clusters, cliquez sur cette valeur.
Espace de noms
g.co/r/k8s_container/namespace 		Identifie l'espace de noms. Pour accéder à la page Charges de travail GKE, cliquez sur cette valeur.
Nom du pod
g.co/r/k8s_container/pod_name 		Identifie le pod GKE. Pour accéder au tableau de bord Détails des pods, cliquez sur cette valeur.
Nom du conteneur
g.co/r/k8s_container/container_name 		Identifie le conteneur GKE. Pour accéder à la page des détails du conteneur, cliquez sur cette valeur.

Exemple

Voici une représentation JSON partielle d'un objet Trace incluant plusieurs libellés :

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

La trace précédente a été extraite d'un système utilisant un collecteur Zipkin. Dans ce cas, les libellés avec des clés zipkin.io ont été ajoutés par ce collecteur.

Prefix g.co

Dans certains cas, les étiquettes affichées contiennent un préfixe g.co. Le préfixe g.co indique que ce libellé a été généré par un service Google. Si vous exécutez votre service sur App Engine ou une autre infrastructure Google Cloud, des libellés tels que les suivants peuvent s'afficher :

Clé d'étiquette Exemple de valeur de libellé
g.co/agent opentelemetry-js 1.18.1; google-cloud-trace-exporter 2.1.0
g.co/r/generic_node/location global

Libellés personnalisés

Vous pouvez créer des libellés personnalisés. Si vous créez un libellé personnalisé, nous vous recommandons d'utiliser les formats suivants :

  • /category/product/key pour les agents de produits connus. Exemple : /db/mongodb/read_size.
  • short_host/path/key pour les clés spécifiques au domaine. Exemple : g.co/agent.

Si vous créez beaucoup de libellés personnalisés, cela peut avoir un impact sur les performances en raison de la cardinalité accrue des libellés.

Comme le montre la section Exemple, si vous utilisez un collecteur Zipkin ou une bibliothèque telle qu'OpenTelemetry, des étiquettes peuvent être ajoutées à vos segments de trace.

Utiliser OpenTelemetry

Si vous utilisez des bibliothèques OpenTelemetry, veillez à utiliser les conventions sémantiques OpenTelemetry lorsque vous créez des segments.