Información de referencia sobre la 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 Especificación
project_id Cadena

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

Si no se encuentra, las funciones de inicialización de observabilidad devuelven un error.
cloud_logging Objeto

Las opciones de registro se clasifican en esta tabla.
Si no está presente, el registro se inhabilita.
cloud_logging.client_rpc_events[] Lista

Lista de configuraciones de client_rpc_events que representa la configuración de las llamadas RPC salientes del archivo binario.

Las configuraciones de client_rpc_events se evalúan por orden de texto y se usa la primera que coincida. Si una llamada a procedimiento remoto no coincide con una entrada, se pasa a la siguiente entrada de la lista.
cloud_logging.client_rpc_events[].methods[] Lista [Cadena]

Lista de identificadores de métodos.

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

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

* se acepta como comodín para:
  • 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 coincida con cualquier [service]/[method]. No se admite cuando client_rpc_events[].exclude es true.
  • El comodín * no se puede usar en el nombre del servicio de forma independiente. */[method] no se admite.

El nombre del servicio, si se especifica, debe ser el nombre de servicio completo, incluido el nombre del paquete.

Ejemplos:
  • goo.Foo/Bar selecciona solo el método Bar del servicio goo.Foo, donde 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 Booleano

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

El valor predeterminado es false, lo que significa que los métodos marcados con client_rpc_events[].methods[] se incluyen en el registro.

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

Número máximo de bytes de metadatos que se deben registrar. Si el tamaño de los metadatos es superior al 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

Número máximo de bytes de cada mensaje que se va a registrar. Si el tamaño del mensaje es superior al límite definido, el contenido que lo supere se truncará.

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

Lista de configuraciones de server_rpc_events que representa la configuración de las llamadas RPC entrantes al archivo binario.

Las configuraciones de server_rpc_events se evalúan en orden de texto. Se usa la primera que coincida. Si una llamada a procedimiento remoto no coincide con una entrada, continúa con la siguiente entrada

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

Lista de cadenas que puede seleccionar un grupo de métodos.

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

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

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

El nombre del servicio, si se especifica, debe ser el nombre de servicio completo, incluido el nombre del paquete.

Ejemplos:
  • goo.Foo/Bar selecciona solo el método Bar del servicio goo.Foo, donde 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 Booleano

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

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

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

Número máximo de bytes de metadatos que se deben registrar. Si el tamaño de los metadatos es superior al 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

Número máximo de bytes de cada mensaje que se va a registrar. Si el tamaño del mensaje es superior al límite definido, se truncará el contenido que supere el límite.

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

Habilita Cloud Monitoring. No hay opciones de configuración. Si proporcionas una objeción de configuración vacía, la monitorización se habilitará. Si no proporcionas un objeto de configuración, la monitorización se inhabilitará.

Por ejemplo, si no se especifica ninguna otra opción, una sección de configuración vacía habilita la monitorización.
export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace Objeto

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, la función de 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 la monitorización de trazas está habilitada, aunque la frecuencia de muestreo sea `0`, se propaga la decisión de muestrear una traza concreta.
cloud_trace.sampling_rate Número

Ajuste global que controla la probabilidad de que se trace una llamada a procedimiento remoto. Por ejemplo:
  • El valor 0.05 significa que hay un 5% de probabilidades de que se trace una RPC.
  • El valor 1.0 significa que se hace un seguimiento de cada llamada.
  • El valor 0 significa que no se deben iniciar nuevos rastreos.

De forma predeterminada, sampling_rate es 0.

El complemento respeta la decisión de muestreo anterior. Si se elige una RPC para el muestreo upstream, el complemento recoge los intervalos y sube los datos al backend, independientemente del ajuste de la frecuencia de muestreo del complemento.
labels Objeto

Un objeto JSON que contiene un conjunto de pares clave-valor. Tanto la clave como el valor son cadenas.

Las etiquetas se aplican a Cloud Logging, Cloud Monitoring y Cloud Trace al mismo tiempo.

Definiciones de trazas

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

Propagación del contexto de rastreo

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

Sin la compatibilidad con la propagación, los servicios posteriores no pueden generar intervalos para un rastreo. Los intervalos que ya tengas no se verán afectados. Los complementos de observabilidad de microservicios admiten el formato binario de OpenCensus para codificar y decodificar el contexto de la traza.

Abarca

El nombre de un intervalo tiene el siguiente formato:

Tipo Valor de ejemplo Uso
Abarca de RPC [Sent|Recv].helloworld.Greeter.SayHello El nombre del intervalo es el nombre completo del método, conectado por puntos y sin barra diagonal inicial.
Los nombres de los intervalos tienen el prefijo Sent. para el intervalo de RPC de CLIENTE y Recv. para el intervalo de RPC de SERVIDOR delante del nombre completo del método.
Intervalo de intentos Attempt.helloworld.Greeter.SayHello Se añade el prefijo Attempt. delante del nombre completo del método.

Etiquetas de intervalo

Las integraciones proporcionan etiquetas de intervalo diferentes.

En el caso de los intervalos de intentos, se adjuntan dos atributos adicionales relacionados con los reintentos (etiquetas de intervalo):

Etiqueta Valor de ejemplo Uso
previous-rpc-attempts 0 Número de intentos de reintento antes de esta llamada a procedimiento remoto.
transparent-retry True/False Indica si esta llamada a procedimiento remoto se ha iniciado mediante un reintento transparente.

Definiciones de las métricas

Las siguientes métricas están disponibles y se muestran en un panel de control llamado Monitorización de microservicios (gRPC) para los recorridos de usuario habituales.

Estas son las métricas del lado del cliente de gRPC:

Nombre de la métrica Descripción Tipo, unidad Etiquetas
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs Número de intentos de RPC de cliente iniciados, incluidos los que no se han completado. Acumulativo, Int64, 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs Número de llamadas a procedimientos remotos 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 total que se tarda en completar un intento de RPC, incluido el tiempo que se tarda en elegir un subcanal. Acumulativo, Distribución, ms grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency Tiempo total que tarda la biblioteca gRPC en completar una llamada a procedimiento remoto 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, no cifrados) enviados en todos los mensajes de solicitud por intento de RPC. Acumulativa, 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, no cifrados) recibidos en todos los mensajes de respuesta por intento de RPC. Acumulativa, Distribución, Por grpc_client_method, grpc_client_status

Están disponibles las siguientes métricas del lado del servidor de gRPC:

Nombre de la métrica Descripción Tipo, unidad Etiquetas
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
Número de RPCs que ha recibido el servidor, incluidas las RPCs que no se han completado.		 Acumulativo, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
El recuento total de RPCs 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
El total de bytes (comprimidos, pero no cifrados) enviados en todos los mensajes de respuesta por RPC.		 Acumulativa, Distribución, Por grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
El total de bytes (comprimidos, no cifrados) recibidos en todos los mensajes de solicitud por RPC.		 Acumulativa, Distribución, Por grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
Tiempo total que tarda una llamada a procedimiento remoto desde la perspectiva del transporte del servidor (HTTP/2, inproc o cronet).		 Acumulativo, Distribución, ms grpc_server_method

Cada distribución de la tabla anterior contiene un histograma con los siguientes segmentos:

  • 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, incluido el paquete, el servicio y el método. Por ejemplo, google.bigtable.v2.Bigtable/CheckAndMutateRow
  • grpc_client_status: código de estado del servidor gRPC recibido. Por ejemplo, OK, CANCELLED o 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 gRPC devuelto. Por ejemplo, OK, CANCELLED o DEADLINE_EXCEEDED.

Definiciones de registros

Los registros de observabilidad de microservicios se suben a Cloud Logging con el nombre de registro (PROJECT_ID es el marcador de posición de la cadena 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 de log 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 Especificación
autoridad Cadena

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

La autoridad es el nombre de dicha identidad de servidor. Normalmente, es una parte del URI en forma de host o host:puerto.
callId Cadena

Identifica de forma exclusiva una llamada [cliente/servidor] que es un UUID. Cada llamada puede tener varias entradas de registro. Todos tienen el mismo callId.
tipo Cadena

Tipo del 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
Registrador String

Tipo del registrador de eventos.

Los tipos de registro de eventos son:
LOGGER_UNKNOWN, CLIENT y SERVER.
serviceName Cadena

Nombre del servicio.
methodName Cadena

Nombre del método RPC.
peer Object

Información de la dirección del peer. En el lado del cliente, el peer se registra en los eventos de encabezado y de tráiler del servidor. En el lado del servidor, el peer siempre se registra en el evento de encabezado del cliente.
peer.type Cadena

Tipo de dirección: IPv4, IPv6 o UNIX.
peer.address Cadena

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

Número de puerto de la dirección. Solo disponible para direcciones IPv4 e IPv6.
carga útil Objeto

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

  • En el caso de los eventos de mensajes, la carga útil son los datos reales que se transfieren como mensajes de cliente o servidor y la longitud del mensaje.
  • En el caso de los eventos de encabezado, la carga útil incluye el nombre y el valor del encabezado.
  • En el caso de los eventos de tráiler, la carga útil incluye detalles del estado junto con los metadatos del tráiler (si los hay).
  • En el caso de los eventos de encabezado del cliente, si se define un tiempo de espera, la carga útil también lo incluye.
payload.timeout Cadena

Cadena que representa google.protobuf.Duration, como "1.2 s".

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

Se usa en eventos de encabezado o de tráiler.
payload.message Cadena (bytes)

Carga útil del mensaje.
payload.messageLength Int

Tamaño del mensaje, independientemente de si se registra el mensaje completo (por ejemplo, se puede truncar u omitir).
payload.statusCode Cadena

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

El mensaje de estado de gRPC.
payload.statusDetails Cadena

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

True si el mensaje o el campo de metadatos se ha truncado u omitido debido a las opciones de configuración.
sequenceId Int

ID de secuencia de mensajes de esta llamada. El primer mensaje tiene el valor 1 para distinguirlo de un valor sin definir. El objetivo de este campo es detectar las entradas que faltan en entornos en los que no se garantiza la durabilidad ni el orden.

Etiquetas de recurso

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

En el caso de las métricas y el seguimiento de las implementaciones de GKE, las etiquetas de recursos se rellenan de forma predeterminada, excepto el nombre del contenedor y el nombre del espacio de nombres. Los valores que faltan se pueden rellenar con la API Downward.

Estas son las claves de las variables de entorno:

  • CONTAINER_NAME
  • NAMESPACE

Por ejemplo, la sección env del siguiente ejemplo 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 proporcionada por los usuarios en los datos de observabilidad. Las etiquetas constan de una clave y un valor. El par clave-valor se adjunta a los datos de seguimiento como etiquetas de intervalo, a los datos de métricas como etiquetas de métricas y a los datos de registro como etiquetas de entrada de registro. Todas las etiquetas personalizadas son de tipo STRING.

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

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

Cada entrada de registro tiene las siguientes etiquetas adicionales:

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

Siguientes pasos