Etiquetas de seguimiento

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

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

Página de lista de seguimiento con etiquetas y un seguimiento de pila.

Hay otras dos ubicaciones donde se muestran las etiquetas. El panel Details muestra las etiquetas HTTP más comunes, mientras que la tabla Trace de llamada enumera el contenido de la etiqueta stacktrace.

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

Existe un límite de 32 etiquetas por intervalo.

Claves predefinidas

En la siguiente tabla, se enumeran las claves predefinidas compatibles, 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 de visualización 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.
/http/client_region La región del cliente.
"us-east4"
/http/host El valor del Encabezado del host.
"default.example.com"
/http/method Configurado 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 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 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 se muestra en la tabla Call Stack.

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

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 mediante 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 en la Vista de cascada de seguimiento 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

Puedes crear etiquetas personalizadas. Si creas una etiqueta personalizada, te recomendamos usar 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 cientos o miles de etiquetas personalizadas, esto podría generar un impacto en 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 OpenCensus

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