Étiquettes Trace

Les libellés et les attributs de Cloud Trace vous permettent d'associer des métadonnées clé/valeur (telles que des codes d'état HTTP, des noms de régions ou des propriétés d'application personnalisées) à vos spans. Vous pouvez ainsi filtrer, regrouper et résoudre les problèmes liés aux requêtes. Si vous utilisez l'API Cloud Trace v1, vous ajoutez des paires clé/valeur à l'aide du champ labels dans l'objet TraceSpan. Si vous utilisez l'API Trace v2, vous devez ajouter des métadonnées à l'aide d'un objet Attributes.

À propos des libellés et des attributs

Le champ labels est une carte de paires clé/valeur stockées sous forme de chaînes, avec une limite de 1 024 libellés par span. Pour connaître les restrictions de longueur des chaînes, consultez la documentation de référence de l'API pour labels.

Lorsque vous explorez un span sur la page Explorateur Trace, les libellés de ce span s'affichent dans l'onglet Attributs, comme illustré dans la capture d'écran suivante :

Exemple de tableau des attributs Cloud Trace.

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

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 HTTP 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 la 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 le tableau Conteneur GKE
Clé d'étiquette		 Description
ID du projet
g.co/r/k8s_container/project_id		 Le 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 .
Emplacement
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://192.0.2.0/",
      "startTime": "2024-04-02T19:37:34.149058Z",
      "endTime": "2025-04-02T19:37:34.151136Z",
      "parentSpanId": "5599906629317525335",
      "labels": {
        "/component": "default",
        "/http/host": "192.0.2.0",
        "/http/status_code": "200",
        "/http/url": "http://192.0.2.0/",
        "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 libellés affichés contiennent le 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 , vous pouvez voir des libellés tels que les suivants :

Clé de l'é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, il est possible que des libellés soient ajoutés à vos spans de trace.

Utiliser OpenTelemetry

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