Étiquettes Trace

Trace vous permet d'ajouter des données pertinentes à votre segments. Si vous utilisez l'API Cloud Trace V1, vous pouvez ajouter des libellés, 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 Ajoutez des annotations d'événement aux délais de trace.

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

Exemple de tableau des 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 de l'agent de suivi.
"node@google-cloud/trace-agent v3.0.0"
/component Identifiant du composant.
"grpc"
/error/message Un message d'erreur.
"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 la demande.
"/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† La route correspondante.
"/cart/checkout/:item_id"
/http/status_code† Code d'état de réponse HTTP.
"200"
/http/url URL de requête HTTP complète.
"http://example.com"
/http/user_agent Informations sur le 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 sont affichés dans le tableau Détails inclus dans la vue 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 tableau de bord GKE dans la console Google Cloud.
Zone géographique
g.co/r/k8s_container/location		 L'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 à l'aide d'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 libellés affichés 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 illustré dans la section Exemple, si vous utilisez un collecteur Zipkin ou une bibliothèque telle qu'OpenTelemetry, des libellés peuvent être ajoutés à vos délais de trace.

Utiliser OpenTelemetry

Si vous utilisez des bibliothèques OpenTelemetry, veillez à utiliser la classe Conventions sémantiques d'OpenTelemetry lors de la création de segments