Étiquettes Trace

Trace fournit un mécanisme vous permettant d'annoter vos délais avec des données pertinentes. Si vous utilisez l'API Cloud Trace V1, vous créez ces annotations à l'aide du champ labels de l'objet TraceSpan de l'API Cloud Trace. Si vous utilisez l'API Cloud Trace V2, vous pouvez annoter avec des attributs. Pour en savoir plus sur les options d'annotation, consultez la page Annoter des délais.

La plupart des libellés sont affichés dans le tableau Labels (Libellés) lorsque la vue en cascade de traces est affichée :

Page

Il existe d'autres emplacements où les libellés sont affichés.

  • Le volet Détails répertorie les libellés HTTP les plus courants.
  • Le tableau Trace d'appel répertorie le contenu du libellé stacktrace. Ce tableau ne s'affiche que si le délai contient une trace de la pile.
  • Le tableau Conteneurs GKE affiche les libellés canoniques d'un conteneur GKE. Chaque ligne du tableau correspond à une étiquette spécifique. La valeur est un lien que vous pouvez utiliser pour afficher plus d'informations sur la ressource.

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.

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

Libellé Value
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 Google Cloud Console.
Cluster Name Identifie le cluster GKE. Pour accéder à la page de configuration Clusters, cliquez sur cette valeur.
Namespace Identifie l'espace de noms. Pour accéder à la page GKE Charges de travail, cliquez sur cette valeur.
Pod Name Identifie le pod GKE. Pour accéder au tableau de bord Informations sur les pods, cliquez sur cette valeur.
Container Name Identifie le conteneur GKE. Pour accéder à la page de 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 ci-dessus 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 dans la vue en cascade de traces 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 opencensus-go[0.15.0]
g.co/gce/instanceid 12345678900000000

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 des centaines ou des milliers 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 que OpenCensus, des libellés peuvent être ajoutés à vos délais de trace.

Utiliser OpenCensus

Si vous utilisez des bibliothèques OpenCensus, vous devez utiliser le nom de l'attribut OpenCensus. Pour trouver une table qui répertorie le nom d'attribut OpenCensus avec le nom de libellé prédéfini Cloud Trace, consultez la page Attributs.