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


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

En este tutorial, aprenderás a usar las funciones de observabilidad de microservicios creando una aplicación gRPC sencilla en Google Cloud con Compute Engine e instrumentando tu aplicación con observabilidad de microservicios. Además, verás cómo se muestran en directo en Monitoring y Logging.

Objetivos

A grandes rasgos, debes hacer lo siguiente:

  • Como desarrollador de servicios, puedes hacer lo siguiente:

    • Crea una aplicación gRPC con el lenguaje que quieras (C++, Go o Java).
    • Habilita tu aplicación y controla el complemento de observabilidad de microservicios.
    • Despliega la aplicación en una máquina virtual de Compute Engine.
  • Como operador de un servicio, puedes usar los datos recogidos de varias formas:

    • Ver trazas en Trace.
    • Consulta las métricas en el panel de monitorización llamado Monitorización de microservicios (gRPC).
    • Ver métricas en el explorador de métricas.
    • Inspecciona las entradas de registro en el explorador de registros.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Cuando termines las tareas que se describen en este documento, puedes evitar que se te siga facturando eliminando los recursos que has creado. Para obtener más información, consulta la sección Limpiar.

Antes de empezar

Consola

  1. 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.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Compute Engine, and Microservices API APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. Create a service account:

    1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator). Learn how to grant roles.
    2. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    3. Select your project.
    4. 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.

    5. Click Create and continue.
    6. 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.

    7. Click Continue.
    8. 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.

    9. Click Done to finish creating the service account.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Compute Engine, and Microservices API APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  9. Create a service account:

    1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator). Learn how to grant roles.
    2. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    3. Select your project.
    4. 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.

    5. Click Create and continue.
    6. 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.

    7. Click Continue.
    8. 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.

    9. Click Done to finish creating the service account.

  10. Consulta la descripción general de la observabilidad de microservicios.
  11. Consulta las dos variables de entorno admitidas, decide cuál quieres usar y determina los valores que requiere la variable de entorno.

cli

  1. 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.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Compute Engine, and Microservices API APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. Create a service account:

    1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator). Learn how to grant roles.
    2. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    3. Select your project.
    4. 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.

    5. Click Create and continue.
    6. Grant the following roles to the service account: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.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.

    7. Click Continue.
    8. 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.

    9. Click Done to finish creating the service account.

  6. Install the Google Cloud CLI.

  7. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  8. Para inicializar gcloud CLI, ejecuta el siguiente comando:

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  10. Verify that billing is enabled for your Google Cloud project.

  11. Enable the Compute Engine, and Microservices API APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  12. Create a service account:

    1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator). Learn how to grant roles.
    2. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
    3. Select your project.
    4. 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.

    5. Click Create and continue.
    6. Grant the following roles to the service account: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.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.

    7. Click Continue.
    8. 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.

    9. Click Done to finish creating the service account.

  13. Install the Google Cloud CLI.

  14. Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

  15. Para inicializar gcloud CLI, ejecuta el siguiente comando:

    gcloud init
  16. Consulta la descripción general de la observabilidad de microservicios.
  17. Consulta las dos variables de entorno admitidas, decide cuál quieres usar y determina los valores que requiere la variable de entorno.

Crear una VM de Compute Engine y conectarse a ella

Sigue estas instrucciones para crear una instancia de VM de Compute Engine y conectarte a ella. En la VM, implementa tu aplicación y, a continuación, instrumenta la aplicación 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
    

Desplegar la aplicación en la máquina virtual de Compute Engine

Puedes desplegar la aplicación que quieras en la VM de Compute Engine que has creado en el paso anterior y, a continuación, saltarte este paso. También puedes usar un ejemplo para seguir las instrucciones en el idioma que prefieras.

C++

  1. Después 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 que tienes instalado Go.

    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 de gRPC-Go.

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

Java

  1. Después de conectarte a la instancia de VM, asegúrate de que tienes 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
    

Crear un 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 tanto en el servidor como en el cliente. La ubicación de este archivo se exportará como GRPC_GCP_OBSERVABILITY_CONFIG_FILE en los pasos posteriores. Sigue las instrucciones que se indican a continuación para configurar los diferentes 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"
  }
}

En las siguientes secciones se incluyen instrucciones para habilitar la recogida de datos en la configuración de los componentes individuales. Si has usado el ejemplo de gRPC de este tutorial, puedes usar esta configuración tal cual (después de actualizar your-project-here) o usarla como plantilla para tu aplicación.También puedes consultar un ejemplo que muestra la información de configuración en una variable de entorno.

Habilitar métricas

Para habilitar las métricas, añade el objeto cloud_monitoring a la configuración y asigna el valor {}.

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

Habilitar el rastreo

Para habilitar el seguimiento, haz lo siguiente:

  1. Añada el objeto cloud_trace a la configuración.
  2. Define cloud_trace.sampling_rate en 0.5 para que se rastree aleatoriamente el 50% de las llamadas a procedimiento remoto.

Si tienes previsto habilitar el seguimiento en varios servicios, asegúrate de que los servicios admitan la propagación del contexto de seguimiento recibido de los servicios anteriores (o iniciado por sí mismos) a los posteriores.

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

Activar el almacenamiento de registros

Para habilitar el registro, haz lo siguiente:

  1. Añada el objeto cloud_logging a la configuración.
  2. Añade un patrón a client_rpc_events o a server_rpc_events (o a ambos) para especificar el conjunto de servicios o métodos para los que quieras generar registros de eventos a nivel de transporte, así como el número de bytes que quieras registrar para los encabezados y los mensajes.

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

Instrumentar las aplicaciones para el complemento de observabilidad

Para instrumentar tus aplicaciones de forma que puedan usar el complemento de observabilidad de microservicios, sigue las instrucciones correspondientes al lenguaje que prefieras.

C++

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

  1. La observabilidad solo está disponible a través del sistema de compilación de Bazel. Añade el grpcpp_gcp_observability de destino como dependencia.

  2. Para habilitar la observabilidad de microservicios, se necesita una dependencia adicional (un módulo de observabilidad) y los siguientes cambios en el código de los clientes, servidores o ambos de gRPC:

    #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, como crear un canal, un servidor o credenciales, invoca lo siguiente:

    grpc::GcpObservability::Init();
    

    Devuelve absl::StatusOr<GcpObservability>, que se debe guardar. El estado ayuda a determinar si la observabilidad se ha inicializado correctamente. El objeto GcpObservability que lo acompaña controla el tiempo de vida de la observabilidad y cierra y vacía automáticamente los datos de observabilidad cuando se sale del ámbito.

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 Go, para habilitar la observabilidad de microservicios, se necesita 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 los exportadores correspondientes e inserta la lógica de recogida de datos en las conexiones de cliente y los servidores creados después de la llamada. La llamada diferida observability.End limpia los recursos y asegura que los datos almacenados en el búfer se vacíen antes de que se cierre la aplicación.

Una vez que se haya actualizado el código de la aplicación, ejecuta el siguiente comando para actualizar el archivo go.mod.

go mod tidy

Java

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

En los fragmentos de compilación de las secciones de herramientas de compilación Gradle y Maven, se ha asignado el valor 1.54.1 a grpcVersion.

El repositorio de ejemplo está en GitHub.

  1. Para instrumentar correctamente tus aplicaciones Java para la observabilidad de microservicios, añade 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 crear canales o servidores gRPC. La función GcpObservability.grpcInit() lee la configuración de observabilidad de microservicios y la usa para configurar los interceptores y los rastreadores globales necesarios para las funciones de registro, métricas y rastreo de cada canal y servidor creados. GcpObservability.grpcInit() es seguro para subprocesos y debe llamarse exactamente una vez. Devuelve una instancia de GcpObservability que debes guardar para llamar a close() más adelante.

GcpObservability.close() desasigna recursos. Los canales o servidores que se creen después no registrarán nada.

GcpObservability implementa java.lang.AutoCloseable, que se cierra automáticamente si usas try-with-resources 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
...
}

Usar la herramienta de compilación Gradle

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

def grpcVersion = '1.54.1'

...

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

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

Si usas la herramienta de compilación 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 has usado el ejemplo de gRPC en el tutorial. Puedes modificar el comando run para orientarlo al archivo binario de tu aplicación.

Ejecutar 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 de 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 de servidor shell go run ./server/main.go

Java

  1. En el directorio de ejemplos, abre el archivo README y sigue las instrucciones que se indican en él.
  2. Cuando las instrucciones te indiquen que abras otra ventana de terminal, introduce este comando: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Ejecutar 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 el 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. Ejecutar 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 arriba para crear el archivo client_config.json. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json
  3. Ejecutar 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 se indican en él.
  2. Cuando se te indique que abras otra ventana de terminal, introduce este comando: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Limpieza

Para evitar que los recursos utilizados en este tutorial se cobren en tu cuenta de Google Cloud, elimina el proyecto que contiene los recursos o conserva el proyecto y elimina los recursos.

Eliminar el proyecto

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

Eliminar recursos concretos

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. Select the checkbox for the instance that you want to delete.
  3. To delete the instance, click More actions, click Delete, and then follow the instructions.

Siguientes pasos