Configura una aplicación de gRPC en Google Cloud con observabilidad de microservicios

---

Las herramientas de observabilidad de microservicios permiten instrumentar aplicaciones para recopilar y presentar datos de telemetría en Cloud Monitoring, Cloud Logging y Cloud Trace desde cargas de trabajo de gRPC implementadas en Google Cloud y en otros lugares. La observabilidad de los microservicios funciona con cualquier implementación a la que se le haya otorgado permiso para acceder a Monitoring, Logging y Trace habilitando la API de microservicios.

En este instructivo, aprenderás a usar las funciones de observabilidad de microservicios. Para esto, debes crear una aplicación sencilla de gRPC en Google Cloud con Compute Engine y, además, instrumentarla con la observabilidad de microservicios. Luego, verás cómo funcionan con Monitoring y Logging.

Objetivos

En términos generales, puedes seguir los pasos que se indican a continuación:

• Como desarrollador de servicios, puedes hacer lo siguiente:

  • Crear una aplicación de gRPC con el lenguaje que prefieras (C++, Go o Java)
  • Habilitar la aplicación y controlar el complemento de observabilidad de microservicios
  • Implementar la aplicación en una VM de Compute Engine

• Como operador de servicios, puedes consumir los datos recopilados de varias maneras:

  • Visualizando rastros en Trace
  • Visualizando métricas en el panel de supervisión llamado Microservices (gRPC) Monitoring
  • Visualizando métricas en el Explorador de métricas
  • Inspeccionando entradas de registros en el Explorador de registros

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• Compute Engine

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Cuando completes las tareas que se describen en este documento, podrás borrar los recursos que creaste para evitar que se te siga facturando. Para obtener más información, consulta Realiza una limpieza.

Antes de empezar

Consola

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine, and Microservices API APIs.

Enable the APIs

Create a service account:

1. In the Google Cloud console, go to the Create service account page.

   Go to Create service account
2. Select your project.

3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

   In the Service account description field, enter a description. For example, Service account for quickstart.

4. Click Create and continue.

5. Grant the following roles to the service account: Logging > Logs Viewer > Logs Writer, Monitoring > Monitoring Editor > Metrics Writer, Trace > Trace Admin > Trace Agent.

   To grant a role, find the Select a role list, then select the role.

   To grant additional roles, click Add another role and add each additional role.

   Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
6. Click Continue.

7. In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

   This is typically the email address for a Google Account.

8. Click Done to finish creating the service account.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine, and Microservices API APIs.

Enable the APIs

Create a service account:

1. In the Google Cloud console, go to the Create service account page.

   Go to Create service account
2. Select your project.

3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

   In the Service account description field, enter a description. For example, Service account for quickstart.

4. Click Create and continue.

5. Grant the following roles to the service account: Logging > Logs Viewer > Logs Writer, Monitoring > Monitoring Editor > Metrics Writer, Trace > Trace Admin > Trace Agent.

   To grant a role, find the Select a role list, then select the role.

   To grant additional roles, click Add another role and add each additional role.

   Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
6. Click Continue.

7. In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

   This is typically the email address for a Google Account.

8. Click Done to finish creating the service account.

1. Lee la Descripción general de la observabilidad de microservicios.
2. Lee sobre las dos variables de entorno compatibles, decide cuál vas a usar y determina los valores que requiere la variable de entorno.

CLI

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
gcloud init
Create or select a Google Cloud project.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.
Make sure that billing is enabled for your Google Cloud project.
Enable the Compute Engine, and Microservices API APIs:
gcloud services enable compute.googleapis.com microservices.googleapis.com
Set up authentication:
1. Create the service account:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name for the service account.

2. Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent:

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • ROLE: the role to grant
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.

3. Grant the required role to the principal that will attach the service account to other resources.

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • USER_EMAIL: the email address for a Google Account

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Make sure that billing is enabled for your Google Cloud project.

Enable the Compute Engine, and Microservices API APIs:

gcloud services enable compute.googleapis.com microservices.googleapis.com

Set up authentication:

1. Create the service account:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name for the service account.

2. Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent:

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • ROLE: the role to grant
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.

3. Grant the required role to the principal that will attach the service account to other resources.

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • USER_EMAIL: the email address for a Google Account
1. Lee la Descripción general de la observabilidad de microservicios.
2. Lee sobre las dos variables de entorno compatibles, decide cuál vas a usar y determina los valores que requiere la variable de entorno.

Crea una VM de Compute Engine y conéctate a ella

Usa estas instrucciones para crear una instancia de VM de Compute Engine y conectarte a ella. En la VM, implementa la aplicación y, luego, instruméntala con la observabilidad de microservicios.

1. Crea una instancia de VM.

   gcloud compute instances create grpc-observability-vm \
     --image-family=debian-11 \
     --image-project=debian-cloud \
     --service-account=SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com
   

2. Conéctate a la instancia de VM.

   gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm
   

Implementa la aplicación en la VM de Compute Engine

Puedes implementar una aplicación de tu elección en la VM de Compute Engine que creaste en el paso anterior y, luego, omitir este paso. De lo contrario, puedes usar un ejemplo para continuar con instrucciones en tu lenguaje de preferencia.

C++

1. Luego de conectarte a la instancia de VM, ejecuta el siguiente comando.

   sudo apt-get update -y
   sudo apt-get install -y git build-essential clang
   git clone -b v1.54.0 https://github.com/grpc/grpc.git --depth=1
   

Go

1. Asegúrate de tener Go instalado.

   sudo apt-get install -y git
   sudo apt install wget
   wget https://go.dev/dl/go1.20.2.linux-amd64.tar.gz
   sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf \
   go1.20.2.linux-amd64.tar.gz
   export PATH=$PATH:/usr/local/go/bin
   

2. Clona los ejemplos gRPC-Go.

   git clone https://github.com/grpc/grpc-go.git
   cd grpc-go/
   git checkout -b run-observability-example
   875c97a94dca8093bf01ff2fef490fbdd576373d
   

Java

1. Luego de conectarte a la instancia de VM, asegúrate de tener instalado Java 8 o una versión posterior.

   sudo apt update
   sudo apt upgrade
   sudo apt install git
   sudo apt-get install -y openjdk-11-jdk-headless
   

2. Clona el repositorio grpc-java.

   export EXAMPLES_VERSION=v1.54.1
   git clone -b $EXAMPLES_VERSION --single-branch --depth=1 \
   https://github.com/grpc/grpc-java.git
   

Crea el archivo de configuración de observabilidad de gRPC Google Cloud

Necesitas un archivo de configuración de observabilidad de gRPC Google Cloud independiente para habilitar la observabilidad de microservicios para el servidor y el cliente. La ubicación de este archivo se exporta como GRPC_GCP_OBSERVABILITY_CONFIG_FILE en los pasos siguientes. Usa las siguientes instrucciones para configurar los distintos parámetros en el archivo de configuración.

Ejemplo GRPC_GCP_OBSERVABILITY_CONFIG_FILE

{
  "project_id": "your-project-here",
  "cloud_logging": {
    "client_rpc_events": [
    {
      "methods": ["google.pubsub.v1.Subscriber/Acknowledge", "google.pubsub.v1.Publisher/CreateTopic"],
      "exclude": true,
    },
    {
      "methods": ["google.pubsub.v1.Subscriber/*", "google.pubsub.v1.Publisher/*"],
      "max_metadata_bytes": 4096,
      "max_message_bytes": 4096,
    }],
    "server_rpc_events": [{
      "methods": ["*"],
      "max_metadata_bytes": 4096,
      "max_message_bytes": 4096
    }],
  },
  "cloud_monitoring": {},
  "cloud_trace": {
    "sampling_rate": 0.5,
  }
  "labels": {
    "SOURCE_VERSION": "J2e1Cf",
    "SERVICE_NAME": "payment-service-1Cf",
    "DATA_CENTER": "us-west1-a"
  }
}

Las siguientes secciones incluyen instrucciones para habilitar la recopilación de datos en la configuración de los componentes individuales. Si usaste el ejemplo de gRPC en este instructivo, puedes usar esta configuración tal como está (luego de actualizar your-project-here) o usarla como plantilla para la aplicación y un ejemplo en el que se muestran los pasos de configuración en una variable de entorno.

Habilita las métricas

Para habilitar las métricas, agrega el objeto cloud_monitoring a la configuración y establece su valor en {}.

Para obtener más información sobre las métricas, consulta Definiciones de métricas.

Habilita el seguimiento

Para habilitar el seguimiento, haz lo siguiente:

1. Agrega el objeto cloud_trace a la configuración.
2. Establece la cloud_trace.sampling_rate en 0.5, que realiza un seguimiento aleatorio del 50% de las RPC.

Si planeas habilitar el seguimiento entre servicios, asegúrate de que admitan la propagación del contexto de seguimiento recibido en sentido upstream (o iniciado por sí mismo) a downstream.

Para obtener más información sobre el seguimiento, consulta Definiciones de seguimiento.

Habilita el registro

Para habilitar el registro, haz lo siguiente:

1. Agrega el objeto cloud_logging a la configuración.
2. Agrega un patrón a client_rpc_events o server_rpc_events, o bien a ambos, que especifique el conjunto de servicios o métodos para los que quieres generar registros de eventos a nivel de transporte y la cantidad de bytes que se registrarán para los encabezados y mensajes.

Para obtener más información sobre el registro, consulta Definiciones de registros.

Instrumenta las aplicaciones para el complemento de observabilidad

Si quieres instrumentar las aplicaciones con el objetivo de que puedan usar el complemento de observabilidad de microservicios, sigue las instrucciones que se indican a continuación para tu lenguaje de preferencia.

C++

Puedes usar C++ con observabilidad de microservicios a partir de gRPC C++ v1.54. El repositorio de ejemplo está en GitHub.

1. La asistencia de observabilidad solo está disponible a través del sistema de compilación de Bazel. Agrega el grpcpp_gcp_observability objetivo como una dependencia.

2. Para habilitar la observabilidad de microservicios, se requiere una dependencia adicional (un módulo de observabilidad). Además, el siguiente código cambia a servidores y clientes de gRPC existentes, o ambos:

   #include <grpcpp/ext/gcp_observability.h>
   
   int main(int argc, char** argv) {
     auto observability = grpc::GcpObservability::Init();
     assert(observability.ok());
     …
     // Observability data flushed when object goes out of scope
   }
   

   Antes de realizar cualquier operación de gRPC, incluida la creación de un canal, un servidor o credenciales, invoca lo siguiente:

   grpc::GcpObservability::Init();
   

   Esto muestra absl::StatusOr<GcpObservability>, que se debe guardar. El estado determina si la observabilidad se inicializó de forma correcta. El objeto GcpObservability adjunto controla la vida útil de la observabilidad y, además, cierra y limpia automáticamente los datos de observabilidad cuando quedan fuera del alcance.

Go

1. Los complementos de observabilidad de microservicios son compatibles con las versiones v1.54.0 y posteriores de gRPC Go. El repositorio de ejemplo está en GitHub.

Con el módulo de Go, habilitar la observabilidad de microservicios requiere un módulo de observabilidad y el siguiente código:

import "google.golang.org/grpc/gcp/observability"

func main() {
  ctx, cancel := context.WithTimeout(context.Background(), time.Second)
  defer cancel()
  if err := observability.Start(ctx); err != nil {
    log.Warning("Unable to start gRPC observability:", err)
  }
  defer observability.End()
  …
}

La llamada observability.Start analiza la configuración de las variables de entorno, crea exportadores según corresponda y, además, incorpora la lógica de recopilación en las conexiones de clientes y en servidores creados luego de la llamada. La llamada diferida observability.End limpia los recursos y garantiza que se limpien los datos almacenados en búfer antes de que se cierre la aplicación.

Luego de actualizar el código de la aplicación, ejecuta el siguiente comando para actualizar el archivo go.mod.

go mod tidy

Java

Si debes usar la observabilidad de microservicios con aplicaciones de Java, modifica la compilación para incluir el artefacto grpc-gcp-observability. Usa la versión 1.54.1 o posterior de gRPC.

En los fragmentos de compilación de las secciones de la herramienta de compilación de Gradle y Maven, grpcVersion se establece en el valor 1.54.1.

El repositorio de ejemplo está en GitHub.

1. Para instrumentar con éxito las aplicaciones de Java para la observabilidad de microservicios, agrega el siguiente código a main().

...
import io.grpc.gcp.observability.GcpObservability;
...

// Main application class
...

public static void main(String[] args) {
...
  // call GcpObservability.grpcInit() to initialize & get observability
  GcpObservability observability = GcpObservability.grpcInit();

...
  // call close() on the observability instance to shutdown observability
  observability.close();
...
}

Ten en cuenta que debes llamar a GcpObservability.grpcInit() antes de que se cree cualquier canal o servidor de gRPC. La función GcpObservability.grpcInit() lee la configuración de observabilidad de microservicios y la usa para ajustar los interceptores y rastreadores globales necesarios para la funcionalidad de registro, métricas y seguimiento en cada canal y servidor creado. GcpObservability.grpcInit() tiene protección de subprocesos y debe llamarse exactamente una vez. Devuelve una instancia de GcpObservability, la cual debes guardar para poder llamar a close() más tarde.

GcpObservability.close() desasigna recursos. Cualquier canal o servidor creado después no realiza genera ningún registro.

GcpObservability implementa java.lang.AutoCloseable, que se cierra automáticamente si usas try-with-resource de la siguiente manera:

...
import io.grpc.gcp.observability.GcpObservability;
...

// Main application class
...

public static void main(String[] args) {
...
  // call GcpObservability.grpcInit() to initialize & get observability
  try (GcpObservability observability = GcpObservability.grpcInit()) {

...
  } // observability.close() called implicitly
...
}

Usa la herramienta de compilación de Gradle

Si usas la herramienta de compilación de Gradle, incluye lo siguiente:

def grpcVersion = '1.54.1'

...

dependencies {
...
implementation "io.grpc:grpc-gcp-observability:${grpcVersion}"
...
}

Usa la herramienta de compilación de Maven (pom.xml)

Si usas la herramienta de compilación de Maven, incluye lo siguiente:

<properties>
...
<grpc.version>1.54.1</grpc.version>
...
</properties>

...

<dependencies>
...
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-gcp-observability</artifactId>
<version>${grpc.version}</version>
</dependency>
...
</dependencies>

Ejecutar la aplicación

Sigue las instrucciones de esta sección solo si usaste el ejemplo de gRPC para el instructivo. Puedes modificar el comando run para orientar el objeto binario de la aplicación.

Ejecuta el servidor

C++

1. Crea una sesión SSH en la VM.

2. Exporta variables de entorno. Sigue los pasos definidos más arriba para crear server_config.json.

     export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
     export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/server_config.json"
   

3. Ejecuta la aplicación del servidor shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server.

Go

1. Crea una sesión SSH en la VM.

2. Exporta variables de entorno. Sigue los pasos definidos más arriba para crear server_config.json.

   export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
   

3. Ejecuta la aplicación del servidor shell go run ./server/main.go.

Java

1. En el directorio de ejemplos, abre el archivo README y sigue las instrucciones que contiene.
2. Cuando se te indique que debes abrir otra ventana de terminal, ejecuta este comando: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Ejecuta el cliente

C++

1. Crea otra sesión SSH en la VM.

2. Exporta variables de entorno. Sigue los pasos definidos más arriba para crear un archivo client_config.json.

     export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
     export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/client_config.json"
   

3. Ejecuta la aplicación cliente.

   cd grpc
   tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_client
   

Go

1. Crea otra sesión SSH en la VM.
2. Exporta variables de entorno. Sigue los pasos definidos más arriba para crear un archivo client_config.json. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json

3. Ejecuta la aplicación cliente.

   cd grpc-go/examples/features/observability
   go run ./client/main.go
   

Java

1. En el directorio de ejemplos, abre el archivo README y sigue las instrucciones que contiene.
2. Cuando se te indique que debes abrir otra ventana de terminal, ejecuta este comando: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o consérvalo y borra los recursos individuales.

Borra el proyecto

Precaución: La eliminación de un proyecto tiene las siguientes consecuencias:

• Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Borra los recursos individuales

1. Borra la instancia:

   gcloud compute instances delete INSTANCE_NAME

¿Qué sigue?

• Si buscas información detallada sobre los datos de configuración y las definiciones de seguimientos, métricas y registros, consulta la referencia de observabilidad de microservicios.
• Si buscas información para ver registros, seguimientos y métricas, consulta Visualiza seguimientos, métricas y entradas de registro.