Etiquetas de Trace

Trace te ofrece un mecanismo para añadir datos significativos a tus spans. Si usas la API Cloud Trace V1, puedes añadir etiquetas, que son pares clave-valor, mediante el campo labels del objeto TraceSpan de la API Cloud Trace. Si usas la versión 2 de la API Cloud Trace, puedes añadir información con un objeto Attributes.

Cuando exploras un intervalo, las etiquetas de ese intervalo se muestran en la pestaña Atributos. Por ejemplo, en la siguiente captura de pantalla se muestra esta pestaña:

Ejemplo de la tabla de atributos de Cloud Trace.

Para obtener información sobre cómo acceder a esta información, consulta Buscar y explorar trazas.

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

Hay un límite de 32 etiquetas por intervalo.

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 del agente de traza.
"node@google-cloud/trace-agent v3.0.0"
/component Identificador del 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 Ciudad del cliente.
"NYC"
/http/client_country El país del cliente.
"US"
/http/client_protocol Identificador del protocolo HTTP.
"1.0"
/http/client_region La región del cliente.
"us-east4"
/http/host Valor del encabezado Host.
"default.example.com"
/http/method† Se asigna al método de solicitud HTTP.
No incluyas esta clave en las solicitudes que no sean HTTP.
"GET"
/http/path† Ruta de la URL de solicitud.
"/cart/checkout"
/http/redirected_url URL anterior a la redirección.
En este caso, use la etiqueta de URL de HTTL para almacenar la URL final.
/http/request/size Número de bytes de la solicitud.
/http/response/size Número de bytes de 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 user-agent HTTP que ha originado la solicitud.
"python-requests/2.19.1"
/stacktrace Seguimiento de pila con formato JSON. Los rastreos 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 V1.
En la API V2, el 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 del seguimiento.

Etiquetas canónicas de GKE

En la siguiente tabla se enumeran todas las etiquetas canónicas de 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 Google Cloud proyecto que aloja el clúster de GKE. Haz clic en el nombre del proyecto para ir al panel de control 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. Para ir a la página de configuración Clusters (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 control 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, haga 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 seguimiento anterior se ha tomado de un sistema que usa un recolector de Zipkin. En este caso, el recolector ha añadido las etiquetas con las claves zipkin.io.

Prefijo g.co

En algunos casos, las etiquetas que se muestran contienen el prefijo g.co. El prefijo g.co indica que esta etiqueta se ha generado mediante un servicio de Google. Si ejecutas tu servicio en App Engine u 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 utilices los siguientes formatos:

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

Si crea muchas etiquetas personalizadas, puede que el rendimiento se vea afectado debido al aumento de la cardinalidad de las etiquetas.

Como se muestra en la sección Ejemplo, si usas un recolector de Zipkin o una biblioteca como OpenTelemetry, es posible que se añadan etiquetas a tus intervalos de seguimiento.

Usar OpenTelemetry

Si usas bibliotecas de OpenTelemetry, asegúrate de usar las convenciones semánticas de OpenTelemetry al crear spans.