Etiquetas de seguimiento

Las etiquetas y los atributos de Cloud Trace te permiten adjuntar metadatos de clave-valor, como códigos de estado HTTP, nombres de regiones o propiedades personalizadas de la aplicación, a tus intervalos para que puedas filtrar, agrupar y solucionar problemas de solicitudes. Si usas la API de Cloud Trace v1, agrega pares clave-valor con el campo labels en el objeto TraceSpan. Si usas la API de Trace v2, agrega metadatos con un objeto Attributes.

Acerca de las etiquetas y los atributos

El campo labels es un mapa de pares clave-valor almacenados como cadenas, con un límite de 1,024 etiquetas por intervalo. Para conocer las restricciones de longitud de cadenas, consulta la referencia de la API para labels.

Cuando exploras un intervalo en la página Explorador de seguimiento, las etiquetas de ese intervalo se muestran en la pestaña Atributos, como se muestra en la siguiente captura de pantalla:

Ejemplo de la tabla de atributos de Cloud Trace.

Para obtener información sobre cómo acceder a esta información, consulta Busca y explora seguimientos.

Claves predefinidas

Etiquetas canónicas

En la siguiente tabla, se enumeran las claves predefinidas admitidas, se incluye una descripción y, en algunos casos, 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 Es el 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 las solicitudes que no sean HTTP.
"GET"
/http/path† Ruta de solicitud-URL.
"/cart/checkout"
/http/redirected_url Es la URL antes del redireccionamiento.
En este caso, usa la etiqueta de URL HTTP 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 Es el seguimiento de pila con formato JSON. Los seguimientos de pila no se indexan para la búsqueda.
Esta etiqueta se muestra en la tabla Pila de llamadas.
La etiqueta /stacktrace solo se usa en la API de V1.
Para la API de 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 Google Cloud que aloja el clúster de GKE. Haz clic en el nombre del proyecto para ir al panel de GKE en la Google Cloud consola.
Ubicación
g.co/r/k8s_container/location		 Ubicación física del clúster de GKE.
Nombre del clúster:
g.co/r/k8s_container/cluster_name 		Identifica el clúster de GKE. Haz clic en este valor para ir a la página de configuración de Clústeres.
Espacio de nombres
g.co/r/k8s_container/namespace 		Identifica el espacio de nombres. Haz clic en este valor para ir a la página Cargas de trabajo de GKE.
Nombre del Pod
g.co/r/k8s_container/pod_name 		Identifica el Pod de GKE. Haz clic en este valor para ir al panel de Detalles de los Pods.
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

A continuación, se muestra 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://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"
      }
    }
  ]
}

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

Prefijo g.co

En algunos casos, las etiquetas que se muestran contienen un prefijo g.co. El prefijo g.co indica que esta etiqueta fue generada por un servicio de Google. Si ejecutas tu 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 opentelemetry-js 1.18.1; google-cloud-trace-exporter 2.1.0
g.co/r/generic_node/location global

Etiquetas personalizadas

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

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

Si creas muchas etiquetas personalizadas, es posible que se produzcan impactos en el rendimiento debido al aumento de la cardinalidad de las etiquetas.

Como se ilustra en la sección Ejemplo, si usas un recopilador de Zipkin o una biblioteca como OpenTelemetry, es posible que se agreguen etiquetas a los intervalos de seguimiento.

Uso de OpenTelemetry

Si usas bibliotecas de OpenTelemetry, asegúrate de usar las Convenciones Semánticas de OpenTelemetry cuando crees intervalos.