Etiquetas de seguimiento

Trace proporciona un mecanismo para que agregues datos significativos a tus intervalos. Si usas la API de Cloud Trace V1, puedes agregar etiquetas, que son pares clave-valor, mediante el campo labels del objeto TraceSpan de la API de Cloud Trace. Si usas la API de Cloud Trace V2, puedes agregar información mediante un objeto Attributes. Para obtener más información, consulta Cómo agregar anotaciones de eventos a los intervalos de seguimiento.

Cuando exploras un intervalo, las etiquetas de ese intervalo se muestran en la pestaña Atributos. Por ejemplo, la siguiente captura de pantalla ilustra 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 Cómo buscar y explorar seguimientos.

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

Existe un límite de 32 etiquetas por intervalo.

Claves predefinidas

Etiquetas canónicas

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

Clave de etiquetaDescripción
Ejemplo
/agent Es el identificador del 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 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 Es el valor del encabezado de host.
"default.example.com"
/http/method† Se establece en el método de solicitud HTTP.
No incluyas esta clave para solicitudes que no son HTTP.
"GET"
/http/path† Ruta de URL de solicitud.
"/cart/checkout"
/http/redirected_url La URL anterior al redireccionamiento.
En este caso, usa la etiqueta de URL HTTL clave para almacenar la URL final.
/http/request/size Cantidad de bytes de 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 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 se muestra en la tabla Call Stack.
La API 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 de un contenedor de GKE:

Nombre visible en la tabla del contenedor de GKE
Clave de etiqueta		 Descripción
ID del proyecto
g.co/r/k8s_container/project_id		 La región de Google Cloud que aloja el clúster de GKE. Haz clic en el nombre del proyecto para ir al panel de GKE en Google Cloud Console.
Ubicación
g.co/r/k8s_container/location		 La 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 de 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 del Pod, 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 parcial de JSON 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 registro anterior se tomó de un sistema que usa un recopilador Zipkin. En este caso, el colector 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 un servicio de Google generó esta etiqueta. 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 opencensus-go[0.15.0]
g.co/gce/instanceid 12345678900000000

Etiquetas personalizadas

Puede 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 las claves específicas del dominio Por ejemplo, g.co/agent

Si creas muchas etiquetas personalizadas, es posible que se vean afectados el rendimiento debido al aumento de la cardinalidad de etiquetas.

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 OpenTelemetry

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