Información de referencia de observabilidad de microservicios

Datos de configuración

Los datos de configuración que se encuentran en las variables de entorno se definen en la siguiente tabla.

Campos Spec
project_id String

El identificador del proyecto al que se envían los datos de observabilidad. Si está vacío, el complemento de observabilidad de gRPC intentará recuperar el ID de projecto de las variables de entorno o de las credenciales predeterminadas.

Si no se encuentra, las funciones init de observabilidad mostrarán un error.
cloud_logging Object

Las opciones de registro se clasifican en esta tabla.
Cuando está ausente, el registro se inhabilita.
cloud_logging.client_rpc_events[] List

Una lista de opciones de configuración de client_rpc_events, que representa la configuración para las RPC salientes del objeto binario.

Las configuraciones client_rpc_events se evalúan en orden de texto; se usa la primera que coincide. Si una RPC no coincide con una entrada, continúa a la siguiente entrada de la lista.
cloud_logging.client_rpc_events[].methods[] List [String]

Una lista de identificadores de métodos.

De forma predeterminada, la lista está vacía y no coincide con ningún método.

El valor del método tiene el formato [service]/[method].

Se acepta * como comodín para lo siguiente:
  • El nombre del método. Si el valor es [service]/*, coincide con todos los métodos del servicio especificado.
  • Todo el valor del campo que coincide con cualquier [service]/[method]. No es compatible cuando client_rpc_events[].exclude es verdadero.
  • El comodín * no se puede usar en el nombre del servicio de forma independiente, no se admite */[method].

Cuando se especifica, el nombre del servicio debe ser el nombre del servicio completamente calificado, incluido el nombre del paquete.

Ejemplos:
  • goo.Foo/Bar selecciona solo el método Bar del servicio goo.Foo, en el que goo es el nombre del paquete.
  • goo.Foo/* selecciona todos los métodos del servicio goo.Foo.
  • * selecciona todos los métodos de todos los servicios.
cloud_logging.client_rpc_events[].exclude Bool

Si los métodos denotados por client_rpc_events[].methods[] deben excluirse del registro.

El valor predeterminado es falso, lo que significa que los métodos denotados por client_rpc_events[].methods[] se incluyen en el registro.

Si el valor es verdadero, el comodín (*) no se puede usar como el valor completo en client_rpc_events[].methods[]..
cloud_logging.client_rpc_events[].max_metadata_bytes Int

Cantidad máxima de bytes de metadatos que se registrarán. Si el tamaño de los metadatos supera el límite definido, no se registrarán los pares clave-valor que superen el límite.

El valor predeterminado es 0, lo que significa que no se registran metadatos.
cloud_logging.client_rpc_events[].max_message_bytes Int

Cantidad máxima de bytes de cada mensaje que se registrará. Si el tamaño del mensaje es mayor que el límite definido, el contenido que excede el límite se trunca.

El valor predeterminado es 0, lo que significa que no se registra ninguna carga útil de mensaje.
cloud_logging.server_rpc_events[] List

Una lista de opciones de configuración server_rpc_events, que representa la configuración para las RPC entrantes del objeto binario.

Las configuraciones server_rpc_events se evalúan en orden de texto; se usa la primera que coincide. Si una RPC no coincide con una entrada, continúa a la siguiente entrada

de la lista.
cloud_logging.server_rpc_events[].methods[] Lista [String]

Una lista de strings que pueden seleccionar un grupo de métodos.

De forma predeterminada, la lista está vacía y no coincide con ningún método.

El valor del método tiene el formato [service]/[method].

Se acepta * como comodín para lo siguiente:
  • El nombre del método. Si el valor es [service]/*, coincide con todos los métodos del servicio especificado.
  • Todo el valor del método que coincide con cualquier [service]/[method]. No se admite cuando server_rpc_events[].exclude es verdadero.
  • El comodín * no se puede usar en el nombre del servicio de forma independiente, no se admite */[method].

Cuando se especifica, el nombre del servicio debe ser el nombre del servicio completamente calificado, incluido el nombre del paquete.

Ejemplos:
  • goo.Foo/Bar selecciona solo el método Bar del servicio goo.Foo, en el que goo es el nombre del paquete.
  • goo.Foo/* selecciona todos los métodos del servicio goo.Foo.
  • * selecciona todos los métodos de todos los servicios.
cloud_logging.server_rpc_events[].exclude Bool

Si los métodos denotados por server_rpc_events[].methods[] deben excluirse del registro.

El valor predeterminado es falso, lo que significa que se registran los métodos denotados por server_rpc_events[].methods[].

Si el valor es verdadero, el comodín (*) no se puede usar como el valor completo en ninguna entrada de server_rpc_events[].methods[].
cloud_logging.server_rpc_events[].max_metadata_bytes Int

Cantidad máxima de bytes de metadatos que se registrarán. Si el tamaño de los metadatos supera el límite definido, no se registrarán los pares clave-valor que superen el límite.

El valor predeterminado es 0, lo que significa que no se registran metadatos.
cloud_logging.server_rpc_events[].max_message_bytes Int

Cantidad máxima de bytes de cada mensaje que se registrará. Si el tamaño del mensaje es mayor que el límite definido, el contenido que excede el límite se trunca.

El valor predeterminado es 0, lo que significa que no se registra ninguna carga útil de mensaje.
cloud_monitoring Objeto

Habilita Cloud Monitoring. No hay opciones de configuración. Si proporcionas una objeción de configuración vacía, la supervisión se habilita. Si no proporcionas un objeto de configuración, la supervisión se inhabilita.

Por ejemplo, cuando no se especifican otras opciones, una sección de configuración vacía habilita la supervisión.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace Object

Una sección de configuración vacía habilita el seguimiento con las opciones de configuración predeterminadas. Si no proporcionas un objeto de configuración, el seguimiento se inhabilita.

Por ejemplo, una sección de configuración vacía habilita el seguimiento con opciones de configuración predeterminadas.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


Cuando el seguimiento está habilitado, incluso con una tasa de muestreo de “0”, la propagación de la muestra se propaga.
cloud_trace.sampling_rate Number

La configuración global que controla la probabilidad de que se realice un seguimiento de una RPC. Por ejemplo:
  • El valor 0.05 significa que hay una probabilidad del 5% de que se realice un seguimiento de una RPC.
  • El valor 1.0 significa que se realiza un seguimiento de cada llamada.
  • El valor 0 significa que no se inician seguimientos nuevos.

De forma predeterminada, la tasa de muestreo es 0.

El complemento respeta la decisión de muestreo en sentido ascendente. Si se elige una RPC para el muestreo ascendente, el complemento recopila intervalos y sube los datos al backend, sin importar la configuración de la tasa de muestreo del complemento.
labels Objeto

Un objeto JSON que contiene un conjunto de pares clave-valor. La clave y el valor son strings.

Las etiquetas se aplican en Cloud Logging, Cloud Monitoring y Cloud Trace juntas.

Definiciones de seguimiento

En esta sección, se proporciona información sobre el seguimiento.

Propagación del contexto de seguimiento

Para que el seguimiento entre servicios funcione, el propietario del servicio debe admitir la propagación del contexto de seguimiento recibido desde ascendente (o iniciado por sí mismo) a descendente. El contexto de seguimiento se propaga entre los servicios a través de los metadatos de gRPC. Asegúrate de habilitar las APIs de Cloud Monitoring, Cloud Logging, Cloud Trace y las de microservicios, que permiten a los servicios de esta configuración informar sus datos de telemetría al servicio correspondiente.

Sin la compatibilidad de propagación, los servicios descendentes no pueden generar intervalos para un seguimiento. Los intervalos existentes no se ven afectados. Los complementos de observabilidad de microservicios admiten el formato binario de OpenCensus para la codificación y el contexto de seguimiento de codificación.

Intervalos

El nombre de un intervalo tiene el siguiente formato:

Tipo Valor de ejemplo Uso
Intervalo de RPC [Sent|Recv].helloworld.Greeter.SayHello El nombre del intervalo es el nombre completo del método, conectado por puntos, sin barra diagonal.
Los nombres de los intervalos tienen el prefijo Sent. para el intervalo CLIENT RPC y Recv. para el intervalo SERVER RPC antes del nombre completo del método.
Intervalo de intento Attempt.helloworld.Greeter.SayHello Adjuntar un prefijo Attempt. antes del nombre completo del método.

Etiquetas de intervalo

Las integraciones proporcionan diferentes etiquetas de intervalo.

Para los intervalos de intento, se adjuntan dos atributos adicionales relacionados con los reintentos (etiquetas de intervalo):

Etiqueta Valor de ejemplo Uso
previous-rpc-attempts 0 La cantidad de reintentos antes de esta RPC.
transparent-retry True/False Indica si esta RPC se inicia mediante un reintento transparente.

Definiciones de las métricas

Las siguientes métricas están disponibles y se muestran en un panel llamado Supervisión de microservicios (gRPC) para recorridos de usuarios comunes:

A continuación, se muestran las métricas de las métricas del cliente de gRPC:

Nombre de la métrica Descripción Similares, tipo, unidad Etiquetas
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs El recuento de intentos de RPC del cliente iniciados, incluidos los que no se completaron. Acumulativo, Int64, 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs El recuento de RPC de cliente completadas, por ejemplo, cuando el servidor recibe o envía una respuesta. Acumulativo, Int64, 1 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency Tiempo de extremo a extremo que se toma para completar un intento de RPC, incluido el tiempo que lleva elegir un subcanal. Acumulativo, distribución, ms grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency El tiempo total que tarda la biblioteca de gRPC en completar una RPC desde la perspectiva de la aplicación. Acumulativo, distribución, ms grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc El total de bytes (comprimidos, sin encriptar) enviados en todos los mensajes de solicitud por intento de RPC. Acumulativo, distribución, por grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc El total de bytes (comprimidos, sin encriptar) recibidos en todos los mensajes de respuesta por intento de RPC. Acumulativo, distribución, por grpc_client_method, grpc_client_status

Las siguientes métricas del servidor de gRPC están disponibles:

Nombre de la métrica Descripción Similares, tipo, unidad Etiquetas
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
El recuento de RPC recibidas en el servidor, incluidas las RPC que no se completaron.		 Acumulativo, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
Es el recuento total de RPC completadas, por ejemplo, cuando el servidor envía una respuesta.		 Acumulativo, Int64, 1 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
Es el total de bytes (comprimidos sin encriptar) que se envían en todos los mensajes de respuesta por RPC.		 Acumulativo, distribución, por grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
Es el total de bytes (comprimidos sin encriptar) que se reciben en todos los mensajes de solicitud por RPC.		 Acumulativo, distribución, por grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
El tiempo total que tomó una RPC desde la perspectiva del transporte del servidor (HTTP2 / inproc / cronet).		 Acumulativo, distribución, ms grpc_server_method

Cada distribución de la tabla anterior contiene un histograma con depósitos de la siguiente manera:

  • Tamaño en bytes: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296

  • Latencia en ms: 0, 0.01, 0.05, 0.1, 0.3, 0.6, 0.8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000

Descripción de la etiqueta:

  • grpc_client_method: Nombre completo del método gRPC, incluidos el paquete, el servicio y el método, por ejemplo, google.bigtable.v2.Bigtable/CheckAndMutateRow
  • grpc_client_status: Código de estado del servidor de gRPC recibido, por ejemplo, OK, CANCELLED, DEADLINE_EXCEEDED
  • grpc_server_method: Nombre completo del método gRPC, incluidos el paquete, el servicio y el método, por ejemplo, com.exampleapi.v4.BookshelfService/Checkout
  • grpc_server_status: Código de estado del servidor de gRPC que se muestra, por ejemplo, OK, CANCELLED, DEADLINE_EXCEEDED

Definiciones de los registros

Los registros de observabilidad de microservicios se suben a Cloud Logging mediante el nombre de registro (PROJECT_ID es el marcador de posición de la string que representa tu proyecto):

logName=projects/[PROJECT_ID]/logs/microservices.googleapis.com%2Fobservability%2Fgrpc

A continuación, se muestra la representación JSON del registro generado:

{
    "authority": string,
    "callId": string,
    "type": string,
    "logger": string,
    "serviceName": string,
    "methodName": string,
    "peer": {
        "type": string,
        "address": string,
        "ipPort": int
    },
    "payload": {
        "timeout": string,
        "metadata":
            {
                string: string,
                string: string
            },
        "statusCode": string,
        "statusMessage": string,
        "statusDetails": string,
        "message": string,
        "messageLength": int,
    },
    "sequenceId": int
}

En la siguiente tabla, se describen los campos de la entrada de registro:

Campos Spec
authority String

Se puede usar un solo proceso para ejecutar varios servidores virtuales con diferentes identidades.

La autoridad es el nombre de esa identidad de servidor. Por lo general, es una parte del URI en forma de host o host:port.
callId String

Identifica de manera inequívoca una llamada [client/server] que es un UUID. Cada llamada puede tener varias entradas de registro. Todas tienen el mismo callId.
tipo String

El tipo de evento de registro.

Los tipos de eventos son los siguientes:
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
logger String

El tipo del registrador de eventos.

Los tipos de registrador de eventos son:
LOGGER_UNKNOWN, CLIENT, SERVER
serviceName String

El nombre del servicio.
methodName String

El nombre del método de RPC.
red con intercambio de tráfico Objeto

Información de dirección del par. En el lado del cliente, el par se registra en los eventos del encabezado del servidor y en los eventos de avance. En el lado del servidor, el par siempre se registra en el evento del encabezado del cliente.
peer.type String

El tipo de dirección, ya sea IPv4, IPv6 o UNIX.
peer.address String

El contenido de la dirección.
peer.ip_port Int

El número de puerto de la dirección. Solo disponible para las direcciones IPv4 e IPv6.
Carga útil Objeto

La carga útil puede incluir una combinación de metadatos, tiempo de espera, mensaje y estado según el evento.

  • Para los eventos de mensajes, la carga útil son datos reales que se pasan como mensajes de cliente/servidor y la extensión del mensaje.
  • Para los eventos de encabezado, la carga útil incluye el nombre y el valor del encabezado.
  • Para los eventos de finalizadores, la carga útil incluye detalles de estado junto con los metadatos del finalizador (si están presentes).
  • En los eventos de encabezado de cliente, si se establece el tiempo de espera, la carga útil también incluye el tiempo de espera.
payload.timeout String

Una string que representa google.protobuf.Duration, como “1.2 s”.

El valor de tiempo de espera de RPC.
payload.metadata Mapping[String, String]

Se usa en el evento de encabezado o de finalizador.
payload.message String (Bytes)

La carga útil del mensaje.
payload.messageLength Int

Tamaño del mensaje, sin importar si el mensaje completo se está registrando (por ejemplo, podría truncarse u omitirse).
payload.statusCode String

El código de estado de gRPC.
payload.statusMessage String

El mensaje de estado de gRPC.
payload.statusDetails String

El valor de la clave de metadatos grpc-status-details-bin, si existe. Este siempre es un mensaje google.rpc.Status codificado.
payloadTruncated Booleano

Es verdadero si el campo de mensaje o metadatos se trunca o se omite debido a las opciones de configuración.
sequenceId Int

El ID de secuencia de mensaje para esta llamada. El primer mensaje tiene un valor de 1 para que no haya ambigmbiedad con un valor no establecido. El propósito de este campo es detectar entradas faltantes en entornos en los que no se garantiza la durabilidad o el orden.

Etiquetas de recursos

Las etiquetas de recursos identifican la fuente que genera datos de observabilidad. Cada etiqueta de ubicación es un par clave-valor, en el que las claves son valores predefinidos que son específicos del entorno de origen (por ejemplo, GKE o Compute Engine).

Para las métricas y el seguimiento en las implementaciones de GKE, las etiquetas de recurso se propagan de forma predeterminada, excepto el nombre del contenedor y el nombre del espacio de nombres. Los valores faltantes se pueden propagar con la API de Downward.

Las siguientes son las claves de variables de entorno:

  • CONTAINER_NAME
  • NAMESPACE

Por ejemplo, la sección env a continuación incluye dos etiquetas de recursos:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: app1
  name: app1
spec:
  replicas: 2
  selector:
    matchLabels:
      run: app1
  template:
    metadata:
      labels:
        run: app1
    spec:
      containers:
        - image: 'o11y-examples:1.00'
          name: container1
          ports:
            - protocol: TCP
              containerPort: 50051
          env:
            - name: CONTAINER_NAME
              value: container1
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

Etiquetas personalizadas

Las etiquetas personalizadas representan información adicional que proporcionan los usuarios en los datos de observabilidad. Las etiquetas consisten en una clave y un valor. El par clave-valor se adjunta al seguimiento de datos como etiquetas de intervalo, datos de métricas como etiquetas de métricas y registros de datos como etiquetas de entrada de registro. Todas las etiquetas personalizadas son del tipo STRING.

Puedes proporcionar etiquetas personalizadas en la configuración si especificas una lista de pares clave-valor para labels. La implementación lee la configuración y crea una etiqueta distinta para cada par clave-valor y, luego, adjunta la etiqueta a los datos de observabilidad. Por ejemplo:

"labels": {
    "DATACENTER": "SAN_JOSE_DC",
    "APP_ID": "24512"
  }

Cada entrada de registro posee las siguientes etiquetas adicionales:

{
   "DATACENTER": "SAN_JOSE_DC"
   "APP_ID": "24512"
}

¿Qué sigue?