gRPC-Anwendung in Google Cloud mit Beobachtbarkeit von Mikrodiensten einrichten


Mit Tools zur Beobachtbarkeit von Mikrodiensten können Sie Ihre Anwendungen instrumentieren, um Telemetriedaten in Cloud Monitoring ,Cloud Logging und Cloud Trace zu erfassen und zu präsentieren, die von gRPC-Arbeitslasten stammen, die in Google Cloud und an anderen Orten bereitgestellt werden. Die Beobachtbarkeit von Mikrodiensten funktioniert mit jeder Bereitstellung, der durch Aktivieren der Microservices API Zugriff auf Monitoring, Logging, und Trace gewährt wurde.

In dieser Anleitung erfahren Sie, wie Sie Features für die Beobachtbarkeit von Mikrodiensten nutzen, indem Sie eine einfache gRPC-Anwendung in Google Cloud mit Compute Engine erstellen und Ihre Anwendung mit Beobachtbarkeit für Mikrodienste instrumentieren und sie live in Monitoring and Logging anzeigen.

Ziele

Auf übergeordneter Ebene führen Sie diese Schritte aus.

  • Als Dienstentwickler haben Sie folgende Möglichkeiten:

    • Erstellen Sie eine gRPC-Anwendung in der Sprache Ihrer Wahl (C++, Go oder Java).
    • Aktivieren Sie das Plug-in für die Beobachtbarkeit von Mikrodiensten für Ihre Anwendung und steuern Sie es.
    • Die Anwendung auf einer Compute Engine-VM bereitstellen
  • Als Dienstoperator nutzen Sie die erfassten Daten auf verschiedene Arten:

    • Traces in Trace ansehen.
    • Rufen Sie die Messwerte im Monitoring-Dashboard „Microservices (gRPC) Monitoring“ auf.
    • Messwerte in Metrics Explorer aufrufen.
    • Logeinträge im Log-Explorer prüfen.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Nach Abschluss der in diesem Dokument beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen. Weitere Informationen finden Sie unter Bereinigen.

Hinweis

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.

    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.

    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.

    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.

    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. Lesen Sie die Übersicht über Mikrodienst-Beobachtbarkeit.
  11. Lesen Sie über die zwei unterstützten Umgebungsvariablen nach und entscheiden Sie, welche verwendet werden soll, und ermitteln Sie die Werte, die für die Umgebungsvariable erforderlich sind.

Befehlszeile

  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.

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

    • 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
    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. Lesen Sie die Übersicht über Mikrodienst-Beobachtbarkeit.
  15. Lesen Sie über die zwei unterstützten Umgebungsvariablen nach und entscheiden Sie, welche verwendet werden soll, und ermitteln Sie die Werte, die für die Umgebungsvariable erforderlich sind.

Compute Engine-VM erstellen und Verbindung zu dieser herstellen

Folgen Sie dieser Anleitung, um eine Compute Engine-VM-Instanz zu erstellen und eine Verbindung zu ihr herzustellen. Sie stellen Ihre Anwendung auf der VM bereit und instrumentieren sie dann mit der Beobachtbarkeit von Mikrodiensten.

  1. Erstellen Sie eine VM-Instanz:

    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. Verbindung zur VM-Instanz herstellen

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

Anwendung auf der Compute Engine-VM bereitstellen

Sie können entweder eine Anwendung Ihrer Wahl auf der Compute Engine-VM bereitstellen, die Sie im vorherigen Schritt erstellt haben, und dann diesen Schritt überspringen, oder Sie können ein Beispiel verwenden, um mit der Anleitung in Ihrer bevorzugten Sprache fortzufahren.

C++

  1. Nachdem Sie eine Verbindung zur VM-Instanz hergestellt haben, führen Sie den folgenden Befehl aus.

    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. Go muss installiert sein.

    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. Klonen Sie die gRPC-Go-Beispiele.

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

Java

  1. Nachdem Sie eine Verbindung zur VM-Instanz hergestellt haben, prüfen Sie, ob Java 8 oder höher installiert ist.

    sudo apt update
    sudo apt upgrade
    sudo apt install git
    sudo apt-get install -y openjdk-11-jdk-headless
    
  2. Klonen Sie das grpc-java-Repository.

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

gRPC-Konfigurationsdatei für Google Cloud Observability erstellen

Sie benötigen eine separate gRPC-Konfigurationsdatei für die Google Cloud-Beobachtbarkeit, um die Beobachtbarkeit von Mikrodiensten sowohl für den Server als auch für den Client zu aktivieren. Der Speicherort dieser Datei wird in den nächsten Schritten als GRPC_GCP_OBSERVABILITY_CONFIG_FILE exportiert. In der folgenden Anleitung wird beschrieben, wie Sie die verschiedenen Parameter in der Konfigurationsdatei einrichten.

Beispiel 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"
  }
}

In den folgenden Abschnitten finden Sie eine Anleitung zum Aktivieren der Datenerhebung in Ihrer Konfiguration für die einzelnen Komponenten. Wenn Sie das gRPC-Beispiel in dieser Anleitung verwendet haben, können Sie diese Konfiguration unverändert verwenden (nachdem your-project-here aktualisiert) oder dies als Vorlage für Ihre Anwendung und ein Beispiel für die Konfigurationsinformationen in einer Umgebungsvariablen verwenden.

Messwerte aktivieren

Fügen Sie zum Aktivieren von Messwerten das Objekt cloud_monitoring zur Konfiguration hinzu und setzen Sie den Wert auf {}.

Weitere Informationen zu Messwerten finden Sie unter Definitionen von Messwerten.

Tracing aktivieren

So aktivieren Sie Tracing:

  1. Fügen Sie das Objekt cloud_trace zur Konfiguration hinzu.
  2. Legen Sie cloud_trace.sampling_rate auf 0.5 fest, um 50% der RPCs nach dem Zufallsprinzip zu erfassen.

Wenn Sie das Tracing über Dienste hinweg aktivieren möchten, müssen Sie dafür sorgen, dass die Dienste die Weitergabe von Trace-Kontext vom vorgelagerten (oder selbst gestarteten) zum nachgelagerten Dienst unterstützen.

Weitere Informationen zum Tracing finden Sie unter Trace-Definitionen.

Logging aktivieren

So aktivieren Sie das Logging:

  1. Fügen Sie das Objekt cloud_logging zur Konfiguration hinzu.
  2. Fügen Sie ein Muster entweder zu client_rpc_events, zu server_rpc_events oder zu beiden hinzu, um die Dienste oder Methoden anzugeben, für die Sie ein Ereignis-Logging auf Transportebene generieren möchten und die Anzahl der zu protokollierenden Byte für Header und Nachrichten.

Weitere Informationen zum Logging finden Sie unter Definitionen von Logeinträgen.

Anwendungen für das Beobachtbarkeits-Plug-in instrumentieren

Verwenden Sie die folgende Anleitung für Ihre bevorzugte Sprache, um Ihre Anwendungen so zu instrumentieren, dass sie das Mikrodienste-Beobachtbarkeits-Plug-in verwenden können.

C++

Sie können C++ mit der Beobachtbarkeit von Mikrodiensten ab gRPC C++ v1.54 verwenden. Das Beispiel-Repository befindet sich auf GitHub.

  1. Der Support für die Beobachtbarkeit ist nur über das Bazel-Buildsystem verfügbar. Fügen Sie das Ziel grpcpp_gcp_observability als Abhängigkeit hinzu.

  2. Die Aktivierung der Beobachtbarkeit von Mikrodiensten erfordert eine zusätzliche Abhängigkeit (ein Beobachtbarkeitsmodul) und die folgenden Codeänderungen an vorhandenen gRPC-Clients, -Servern oder beidem:

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

    Führen Sie vor allen gRPC-Vorgängen, einschließlich dem Erstellen eines Kanals, Servers oder Anmeldedaten, Folgendes aus:

    grpc::GcpObservability::Init();
    

    Es wird absl::StatusOr<GcpObservability> zurückgegeben, was gespeichert werden sollte. Der Status hilft bei der Feststellung, ob die Beobachtbarkeit erfolgreich initialisiert wurde. Das zugehörige GcpObservability-Objekt steuert die Lebensdauer der Beobachtbarkeit und schließt und entfernt Daten zur Beobachtbarkeit automatisch, wenn sie außerhalb des Gültigkeitsbereichs liegen.

Go

  1. Plug-ins für Beobachtbarkeit von Mikrodiensten werden in gRPC Go-Versionen v1.54.0 und höher unterstützt. Das Beispiel-Repository befindet sich auf GitHub.

Wenn Sie die Beobachtbarkeit von Mikrodiensten aktivieren, sind für das Go-Modul ein Beobachtbarkeitsmodul und der folgende Code erforderlich:

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

Der Aufruf observability.Start parst die Konfiguration aus Umgebungsvariablen, erstellt entsprechend Exporter und fügt eine Erfassungslogik in Clientverbindungen und Server ein, die nach dem Aufruf erstellt werden. Der zurückgestellte Aufruf observability.End bereinigt Ressourcen und stellt sicher, dass die Daten im Zwischenspeicher gelöscht werden, bevor die Anwendung geschlossen wird.

Führen Sie nach dem Aktualisieren des Anwendungscodes den folgenden Befehl aus, um die Datei go.mod zu aktualisieren.

go mod tidy

Java

Um die Beobachtbarkeit von Mikrodiensten für Java-Anwendungen zu verwenden, ändern Sie den Build so, dass das Artefakt grpc-gcp-observability enthalten ist. Verwenden Sie die gRPC-Version 1.54.1 oder höher.

In den Build-Snippets in den Abschnitten der Gradle- und Maven-Build-Tools ist grpcVersion auf den Wert 1.54.1 festgelegt.

Das Beispiel-Repository befindet sich auf GitHub.

  1. Fügen Sie den folgenden Code zu main() hinzu, um Ihre Java-Anwendungen für die Beobachtbarkeit von Mikrodiensten zu instrumentieren.
...
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();
...
}

Sie müssen GcpObservability.grpcInit() aufrufen, bevor gRPC-Kanäle oder -Server erstellt werden. Die Funktion GcpObservability.grpcInit() liest die Konfiguration der Mikrodienst-Beobachtbarkeit und verwendet sie, um die globalen Interceptor und Tracer einzurichten, die für die Logging-, Messwert- und Trace-Funktionalität in jedem erstellten Kanal und Server erforderlich sind. GcpObservability.grpcInit() ist threadsicher und muss genau einmal aufgerufen werden. Die Funktion gibt eine Instanz von GcpObservability zurück, die Sie speichern müssen, um später close() aufrufen zu können.

GcpObservability.close() hebt die Zuweisung von Ressourcen auf. Kanäle, die danach erstellt werden, führen kein Logging durch.

GcpObservability implementiert java.lang.AutoCloseable, das automatisch geschlossen wird, wenn Sie try-with-resources so verwenden:

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

Gradle-Build-Tool verwenden

Wenn Sie das Gradle-Build-Tool verwenden, geben Sie Folgendes an:

def grpcVersion = '1.54.1'

...

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

Maven-Build-Tool (pom.xml) verwenden

Wenn Sie das Maven-Build-Tool verwenden, geben Sie Folgendes an:

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

Führen Sie Ihre Anwendung aus

Folgen Sie der Anleitung in diesem Abschnitt nur, wenn Sie das gRPC-Beispiel für die Anleitung verwendet haben. Sie können den Befehl run so ändern, dass er auf das Binärprogramm Ihrer Anwendung ausgerichtet ist.

Run Server

C++

  1. Erstellen Sie eine SSH-Sitzung in der VM.
  2. Exportieren Sie Umgebungsvariablen. Erstellen Sie server_config.json mithilfe der oben beschriebenen Schritte.

      export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
      export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/server_config.json"
    
  3. Serveranwendung ausführen shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server

Go

  1. Erstellen Sie eine SSH-Sitzung in der VM.
  2. Exportieren Sie Umgebungsvariablen. Erstellen Sie server_config.json mithilfe der oben beschriebenen Schritte.

    export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
    
  3. Serveranwendung ausführen shell go run ./server/main.go

Java

  1. Öffnen Sie im Verzeichnis „examples“ die README-Datei und folgen Sie der Anleitung darin.
  2. Wenn Sie in der Anleitung aufgefordert werden, ein weiteres Terminalfenster zu öffnen, geben Sie diesen Befehl ein: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Run Client

C++

  1. Erstellen Sie eine weitere SSH-Sitzung in der VM.
  2. Exportieren Sie Umgebungsvariablen. Erstellen Sie die client_config.json-Datei mit den oben beschriebenen Schritten.

      export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
      export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/client_config.json"
    
  3. Clientanwendung ausführen

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

Go

  1. Erstellen Sie eine weitere SSH-Sitzung in der VM.
  2. Exportieren Sie Umgebungsvariablen. Führen Sie die oben beschriebenen Schritte aus, um die client_config.json-Datei zu erstellen. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json
  3. Clientanwendung ausführen

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

Java

  1. Öffnen Sie im Verzeichnis „examples“ die README-Datei und folgen Sie der Anleitung.
  2. Wenn Sie in der Anleitung aufgefordert werden, ein weiteres Terminalfenster zu öffnen, geben Sie diesen Befehl ein: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie entweder das Projekt, das die Ressourcen enthält, oder Sie behalten das Projekt und löschen die einzelnen Ressourcen.

Projekt löschen

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

Einzelne Ressourcen löschen

  1. Löschen Sie die Instanz:
    gcloud compute instances delete INSTANCE_NAME

Nächste Schritte