Configurer une application gRPC sur Google Cloud avec l'observabilité des microservices

---

Les outils d'observabilité des microservices vous permettent d'instrumenter vos applications pour collecter et présenter des données de télémétrie dans Cloud Monitoring, Cloud Logging et Cloud Trace à partir de charges de travail gRPC déployées sur Google Cloud et ailleurs. L'observabilité des microservices fonctionne avec tout déploiement autorisé à accéder à Monitoring, Logging et Trace en activant l'API Microservices.

Dans ce tutoriel, vous allez apprendre à utiliser les fonctionnalités d'observabilité des microservices en créant une application gRPC simple sur Google Cloud à l'aide de Compute Engine. Vous apprendrez également à instrumenter votre application avec l'observabilité des microservices et à les afficher en direct sur Monitoring et Logging.

Objectifs

De manière générale, vous procédez comme suit :

• En tant que développeur de service, vous pouvez :

  • Créer une application gRPC avec le langage de votre choix (C++, Go ou Java).
  • Activer votre application et contrôler le plug-in d'observabilité des microservices.
  • Déployer l'application sur une VM Compute Engine.

• En tant qu'opérateur de service, vous utilisez les données collectées de différentes manières :

  • Afficher les traces sur Trace.
  • Afficher les métriques dans le tableau de bord de surveillance appelé Microservices (gRPC) Monitoring.
  • Afficher les métriques dans l'Explorateur de métriques.
  • Inspecter les entrées de journal dans l'explorateur de journaux.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• Compute Engine

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Une fois que vous avez terminé les tâches décrites dans ce document, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Console

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.

   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

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

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

   Enable the APIs

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

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

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

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

   Enable the APIs

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

10. Consultez la présentation de l'observabilité des microservices.
11. Découvrez les deux variables d'environnement compatibles, décidez lesquelles utiliser et déterminez les valeurs requises par la variable d'environnement.

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. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

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

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

6. Enable the Compute Engine, and Microservices API APIs:

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

7. 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
8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

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

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

12. Enable the Compute Engine, and Microservices API APIs:

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

13. 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
14. Consultez la présentation de l'observabilité des microservices.
15. Découvrez les deux variables d'environnement compatibles, décidez lesquelles utiliser et déterminez les valeurs requises par la variable d'environnement.

Créer une VM Compute Engine et s'y connecter

Suivez ces instructions pour créer une instance de VM Compute Engine et vous y connecter. Sur la VM, vous déployez votre application, puis vous l'instrumentez avec l'observabilité des microservices.

1. Créez une instance 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. Connectez-vous à l'instance de VM :

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

Déployer votre application sur la VM Compute Engine

Vous pouvez choisir de déployer l'application de votre choix sur la VM Compute Engine que vous avez créée à l'étape précédente, puis ignorer cette étape, ou vous pouvez utiliser un exemple pour continuer à suivre les instructions dans le langage de votre choix.

C++

1. Une fois connecté à l'instance de VM, exécutez la commande suivante.

   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. Assurez-vous que Go est installé.

   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. Clonez les exemples gRPC-Go.

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

Java

1. Une fois que vous êtes connecté à l'instance de VM, assurez-vous que Java 8 ou une version ultérieure est installée.

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

2. Clonez le dépôt grpc-java.

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

Créer le fichier de configuration Google Cloud Observability gRPC

Vous avez besoin d'un fichier de configuration gRPC Google Cloud Observability distinct pour activer l'observabilité des microservices pour le serveur et le client. L'emplacement de ce fichier sera exporté en tant que GRPC_GCP_OBSERVABILITY_CONFIG_FILE lors des prochaines étapes. Utilisez les instructions suivantes pour configurer les différents paramètres dans le fichier de configuration.

Exemple de fichier 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"
  }
}

Les sections suivantes contiennent des instructions concernant l'activation de la collecte des données dans votre configuration pour les composants individuels. Si vous avez utilisé l'exemple gRPC dans ce tutoriel, vous pouvez utiliser cette configuration telle quelle (après avoir mis à jour your-project-here) ou l'utiliser comme modèle pour votre application ainsi qu'un exemple montrant les informations de configuration dans une variable d'environnement.

Activer les métriques

Pour activer les métriques, ajoutez l'objet cloud_monitoring à la configuration et définissez sa valeur sur {}.

Pour en savoir plus sur les métriques, consultez la page Définitions des métriques.

Activer le traçage

Pour activer le traçage, procédez comme suit :

1. Ajoutez l'objet cloud_trace à la configuration.
2. Définissez cloud_trace.sampling_rate sur 0.5 pour tracer de manière aléatoire 50 % des RPC.

Si vous envisagez d'activer le traçage sur plusieurs services, assurez-vous que les services sont compatibles avec la propagation du contexte de trace reçu de l'amont (ou démarré par lui-même) vers l'aval.

Pour en savoir plus sur le traçage, consultez la page Définitions de trace.

Activer la journalisation

Pour activer la journalisation, procédez comme suit :

1. Ajoutez l'objet cloud_logging à la configuration.
2. Ajoutez un modèle à client_rpc_events ou à server_rpc_events, ou aux deux, en spécifiant l'ensemble de services ou de méthodes pour lesquels vous souhaitez générer une journalisation des événements au niveau du transport, ainsi que le nombre d'octets à consigner pour les en-têtes et les messages.

Pour en savoir plus sur la journalisation, consultez la section Définitions des enregistrements de journal.

Instrumenter vos applications pour le plug-in d'observabilité

Pour instrumenter vos applications afin qu'elles puissent utiliser le plug-in d'observabilité des microservices, suivez les instructions correspondant au langage de votre choix.

C++

Vous pouvez utiliser C++ avec l'observabilité des microservices à partir de la version gRPC de C++ v1.54. L'exemple de dépôt se trouve dans GitHub.

1. La compatibilité de l'observabilité n'est assurée que via le système de compilation Bazel. Ajoutez la cible grpcpp_gcp_observability en tant que dépendance.

2. L'activation de l'observabilité des microservices nécessite une dépendance supplémentaire (un module d'observabilité) et les modifications de code suivantes sur les clients et serveurs gRPC existants, ou les deux :

   #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
   }
   

   Avant toute opération gRPC, y compris pour créer un canal, un serveur ou des identifiants, appelez la commande suivante :

   grpc::GcpObservability::Init();
   

   Cette commande renvoie absl::StatusOr<GcpObservability>, qui doit être enregistré. L'état permet de déterminer si l'observabilité a bien été initialisée. L'objet GcpObservability associé contrôle la durée de vie de l'observabilité, en plus de fermer et de vider automatiquement les données d'observabilité lorsqu'elles sont hors du champ d'application.

Go

1. Les plug-ins d'observabilité des microservices sont compatibles avec les versions de Go gRPC v1.54.0 et ultérieures. L'exemple de dépôt se trouve dans GitHub.

Avec le module Go, l'activation de l'observabilité des microservices nécessite un module d'observabilité et le code suivant :

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()
  …
}

L'appel observability.Start analyse la configuration à partir de variables d'environnement, crée des exportateurs en conséquence et injecte une logique de collecte dans les connexions client et les serveurs créés après l'appel. L'appel observability.End différé nettoie les ressources et garantit que les données mises en mémoire tampon sont vidées avant la fermeture de l'application.

Une fois le code de l'application mis à jour, exécutez la commande suivante pour mettre à jour le fichier go.mod.

go mod tidy

Java

Pour utiliser l'observabilité des microservices avec des applications Java, modifiez votre compilation afin d'inclure l'artefact grpc-gcp-observability. Utilisez gRPC version 1.54.1 ou ultérieure.

Dans les extraits de code des sections de Gradle et de l'outil de compilation Maven, grpcVersion est défini sur la valeur 1.54.1.

L'exemple de dépôt se trouve dans GitHub.

1. Pour réussir l'observabilité de vos applications Java pour l'observabilité des microservices, ajoutez le code suivant à 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();
...
}

Notez que vous devez appeler GcpObservability.grpcInit() avant la création des canaux ou serveurs gRPC. La fonction GcpObservability.grpcInit() lit la configuration d'observabilité des microservices et l'utilise pour configurer les intercepteurs et les traceurs globaux requis pour la journalisation, les métriques et les fonctionnalités de traces dans chaque canal et serveur créés. GcpObservability.grpcInit() est sécurisé et doit être appelé exactement une fois. Cela renvoie une instance de GcpObservability que vous devez enregistrer pour appeler close() ultérieurement.

GcpObservability.close() libère des ressources. Les canaux ou serveurs créés par la suite n'effectuent aucune journalisation.

GcpObservability met en œuvre java.lang.AutoCloseable, qui est fermé automatiquement si vous utilisez try-with-resource comme suit :

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

Utiliser l'outil de création Gradle

Si vous utilisez l'outil de création Gradle, incluez les éléments suivants :

def grpcVersion = '1.54.1'

...

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

Utiliser l'outil de création Maven (pom.xml

Si vous utilisez l'outil de création Maven, incluez les éléments suivants :

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

Exécuter votre application

Suivez les instructions de cette section uniquement si vous avez utilisé l'exemple gRPC pour le tutoriel. Vous pouvez modifier la commande run pour cibler le binaire de votre application.

Exécuter le serveur

C++

1. Créez une session SSH dans la VM.

2. Exportez les variables d'environnement. Suivez les étapes définies ci-dessus pour créer le fichier 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. Exécutez l'application de serveur shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server.

Go

1. Créez une session SSH dans la VM.

2. Exportez les variables d'environnement. Suivez les étapes définies ci-dessus pour créer le fichier server_config.json.

   export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
   

3. Exécutez l'application de serveur shell go run ./server/main.go.

Java

1. Dans le répertoire d'exemples, ouvrez le fichier README et suivez les instructions qu'il contient.
2. Lorsque les instructions vous indiquent d'ouvrir une autre fenêtre de terminal, exécutez la commande suivante : shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Exécuter le client

C++

1. Créez une autre session SSH dans la VM.

2. Exportez les variables d'environnement. Suivez les étapes définies ci-dessus pour créer le fichier 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. Exécutez l'application cliente.

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

Go

1. Créez une autre session SSH dans la VM.
2. Exportez les variables d'environnement. Suivez les étapes définies ci-dessus pour créer le fichier client_config.json. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json

3. Exécutez l'application cliente.

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

Java

1. Dans le répertoire d'exemples, ouvrez le fichier README et suivez les instructions qu'il contient.
2. Lorsque les instructions vous indiquent d'ouvrir une autre fenêtre de terminal, exécutez la commande suivante : shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Supprimer le projet

Attention : La suppression d'un projet entraîne les effets décrits ci-dessous :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Supprimer des ressources individuelles

1. Supprimez l'instance.

   gcloud compute instances delete INSTANCE_NAME

Étape suivante

• Pour en savoir plus sur les données de configuration, les définitions de traces, les définitions de métriques et les définitions de journaux, consultez la documentation de référence sur l'observabilité des microservices.
• Pour en savoir plus sur l'affichage des journaux, des traces et des métriques, consultez la section Afficher les traces, les métriques et les entrées de journal.