Etiquetas de seguimiento

Trace proporciona un mecanismo para anotar los intervalos con datos significativos. Si usas la API de Cloud Trace V1, debes crear estas anotaciones mediante el campo labels en la API de Cloud Trace TraceSpan.. Si usas la API de Cloud Trace V2, puedes anotar con atributos. Para obtener más información sobre las opciones de anotación, consulta Anota intervalos.

La mayoría de las etiquetas aparecen en la tabla Etiquetas cuando se muestra la vista de cascada de Trace:

Página de lista de seguimiento en la que se muestran las etiquetas y un seguimiento de pila.

Hay otros lugares donde se muestran las etiquetas:

  • En el panel Detalles (Details), se enumeran las etiquetas HTTP más comunes.
  • En la tabla Pila de llamadas, se muestra el contenido de la etiqueta stacktrace. Esta tabla solo se muestra si el intervalo contiene un seguimiento de pila.
  • En la tabla Contenedores de GKE, se muestran las etiquetas canónicas de un contenedor de GKE. Cada fila de la tabla corresponde a una etiqueta específica, y el valor es un vínculo que puedes usar para ver información sobre el recurso con más detalle.

El campo labels es un mapa de pares clave-valor. Las claves y los valores se almacenan como strings. Para conocer las restricciones de longitud de las strings, consulta la referencia de la API para labels.

Hay un límite de 32 etiquetas por intervalo.

Claves predefinidas

Etiquetas canónicas

En la siguiente tabla, se enumeran las claves predefinidas que se admiten, se incluye una descripción y, en algunos casos, se incluye un ejemplo:

Clave de etiquetaDescripción
Ejemplo
/agent Identificador de agente de seguimiento.
"node@google-cloud/trace-agent v3.0.0"
/component Identificador de componente.
"grpc"
/error/message Un mensaje de error.
"Rendezvous of RPC that terminated with:
status = StatusCode.UNAVAILABLE details = OS Error."
/error/name Nombre visible del error.
/http/client_city La ciudad del cliente.
"NYC"
/http/client_country El país del cliente.
"US"
/http/client_protocol Identificador de protocolo HTTP.
"1.0"
/http/client_region La región del cliente.
"us-east4"
/http/host El valor del Encabezado del host.
"default.example.com"
/http/method Se establece en el método de solicitud HTTP.
No incluyas esta clave para solicitudes que no sean HTTP.
"GET"
/http/path Ruta de solicitud-URL.
"/cart/checkout"
/http/redirected_url La URL antes del redireccionamiento.
En este caso, use la etiqueta de URL HTTL clave para almacenar la URL final.
/http/request/size Cantidad de bytes en la solicitud.
/http/response/size Cantidad de bytes en la respuesta.
/http/route La ruta coincidente.
"/cart/checkout/:item_id"
/http/status_code Código de estado de respuesta HTTP.
"200"
/http/url URL de solicitud HTTP completa.
"http://example.com"
/http/user_agent Información sobre el usuario-agente de HTTP que originó la solicitud.
"python-requests/2.19.1"
/stacktrace Seguimiento de pila con formato JSON. Los seguimientos de pila no se indexan para la búsqueda.
Esta etiqueta aparece en la tabla Call Stack.
La etiqueta V1 solo usa la etiqueta /stacktrace.
Para la API V2, span contiene un campo 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"
          }
        ]
      }
    },

Esta etiqueta y su valor se muestran en la tabla Detalles que se incluye en la vista Detalles de seguimiento.

Etiquetas canónicas para GKE

En la siguiente tabla, se enumeran todas las etiquetas canónicas para un contenedor de GKE:

Nombre visible en la tabla Contenedor de GKE
Clave de etiqueta
Descripción
ID del proyecto
g.co/r/k8s_container/project_id
El proyecto de Google Cloud en el que se aloja el clúster de GKE. Haz clic en el nombre del proyecto para ir al panel de GKE en Google Cloud Console.
Nombre del clúster
g.co/r/k8s_container/cluster_name
Identifica el clúster de GKE. Para ir a la página de configuración Clústeres, haz clic en este valor.
Espacio de nombres
g.co/r/k8s_container/namespace
Identifica el espacio de nombres. Para ir a la página Cargas de trabajo de GKE, haz clic en este valor.
Nombre del Pod
g.co/r/k8s_container/pod_name
Identifica el Pod de GKE. Para ir al panel de Detalles de los pods, haz clic en este valor.
Nombre del contenedor
g.co/r/k8s_container/container_name
Identifica el contenedor de GKE. Para ir a la página de detalles del contenedor, haz clic en este valor.

Ejemplo

La siguiente es una representación JSON parcial de un objeto Trace que incluye varias etiquetas:

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

El seguimiento anterior se tomó de un sistema que usa un recopilador Zipkin. En este caso, ese colector agregó las etiquetas con claves zipkin.io.

Prefijo g.co

En algunos casos, las etiquetas que se muestran en la vista de cascada de Trace contienen un prefijo g.co. El prefijo g.co indica que un servicio de Google generó esta etiqueta. Si ejecutas el servicio en App Engine o en otra infraestructura de Google Cloud, es posible que veas etiquetas como las siguientes:

Clave de etiqueta Valor de etiqueta de muestra
g.co/agent opencensus-go[0.15.0]
g.co/gce/instanceid 12345678900000000

Etiquetas personalizadas

Puedes crear etiquetas personalizadas. Si creas una etiqueta personalizada, te recomendamos que uses los siguientes formatos:

  • /category/product/key para los agentes de productos conocidos Por ejemplo, /db/mongodb/read_size
  • short_host/path/key para claves de dominio específicas Por ejemplo, g.co/agent

Si creas muchas etiquetas personalizadas, eso podría generar un impacto en el rendimiento debido al aumento de la cardinalidad de la etiqueta.

Como se ilustra en la sección Ejemplo, si usas un colector Zipkin o una biblioteca como OpenCensus, podría agregar etiquetas a tus intervalos de seguimiento.

Usa OpenCensus

Si usas bibliotecas de OpenCensus, debes usar el nombre del atributo de OpenCensus. Para encontrar una tabla que incluya una lista cruzada del nombre del atributo de OpenCensus con el nombre de etiqueta predefinida de Cloud Trace, consulta Atributos.