הגדרת אפליקציית gRPC ב-Google Cloud עם ניראות של מיקרו-שירותים

כלי התצפית על מיקרו-שירותים מאפשרים לכם להגדיר את האפליקציות שלכם לאיסוף ולהצגה של נתוני טלמטריה ב-Cloud Monitoring, ב-Cloud Logging וב-Cloud Trace מעומסי עבודה של gRPC שנפרסו ב- Google Cloud ובמקומות אחרים. אפשר להשתמש ב-Microservices observability בכל פריסה שקיבלה הרשאה לגשת ל-Monitoring, ל-Logging ול-Trace על ידי הפעלת Microservices API.

במדריך הזה תלמדו איך להשתמש בתכונות של Microservices observability על ידי פיתוח אפליקציית gRPC פשוטה ב- Google Cloud באמצעות Compute Engine, הוספת אינסטרומנטציה לאפליקציה באמצעות Microservices observability וצפייה בהן בזמן אמת ב-Monitoring וב-Logging.

מטרות

ככלל, אלה הפעולות שצריך לבצע:

  • כמפתחי שירותים, אתם יכולים:

    • יוצרים אפליקציית gRPC בשפה שבוחרים (C++‎,‏ Go או Java).
    • להביע הסכמה לשימוש באפליקציה ולשלוט בפלאגין של ניטור המיקרו-שירותים.
    • פריסת האפליקציה במכונה וירטואלית ב-Compute Engine.

  • כמפעילי שירות, אתם יכולים להשתמש בנתונים שנאספו בדרכים שונות:

    • צפייה בעקבות ב-Trace.
    • אפשר לראות את המדדים בלוח הבקרה של המעקב שנקרא Microservices (gRPC) Monitoring (מעקב אחרי מיקרו-שירותים (gRPC)).
    • צפייה במדדים ב-Metrics Explorer.
    • בודקים את הרשומות ביומן ב-Logs Explorer.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

בעזרת מחשבון העלויות אתם יכולים להעריך את העלויות בהתאם לשימוש הצפוי.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

כשמסיימים את המשימות שמתוארות במסמך הזה אפשר למחוק את המשאבים שיצרתם כדי להימנע מחיובים נוספים. מידע נוסף זמין בקטע הסרת המשאבים.

לפני שמתחילים

המסוף

  1. 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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

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

  3. Enable the Compute Engine, and Microservices API APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  4. Create a service account:

    1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin). 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 identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies.

    9. Click Done to finish creating the service account.

  5. סקירה כללית על יכולת תצפית במיקרו-שירותים
  6. קוראים על שני משתני הסביבה הנתמכים, מחליטים באיזה מהם להשתמש ומגדירים את הערכים הנדרשים למשתנה הסביבה.

cli

  1. התקינו את ה-CLI של Google Cloud.

  2. הגדירו שה-CLI של gcloud ישתמש בזהות המאוחדת שלכם.

    איך נכנסים ל-CLI של gcloud באמצעות הזהות המאוחדת?

  3. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  4. יוצרים או בוחרים פרויקט ב- Google Cloud .

    תפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד 'יצירת פרויקטים' (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים?

    • יוצרים פרויקט ב- Google Cloud :

      gcloud projects create PROJECT_ID

      מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.

    • בוחרים את הפרויקט שיצרתם ב- Google Cloud :

      gcloud config set project PROJECT_ID

      מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

  5. מוודאים שהחיוב מופעל בפרויקט Google Cloud .

  6. מפעילים את Compute Engine API ואת Microservices API, אם הם עדיין לא מופעלים:

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים 

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

  7. מגדירים את האימות:

    1. מוודאים שיש לכם את תפקיד ה-IAM ‏Create Service Accounts ‏(roles/iam.serviceAccountCreator) ואת תפקיד ה-IAM ‏Project Admin ‏(roles/resourcemanager.projectIamAdmin). איך מקצים תפקידים

    2. יוצרים את חשבון השירות: 

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      מחליפים את הערך SERVICE_ACCOUNT_NAME בשם שרוצים לתת לחשבון השירות.

    3. נותנים לחשבון השירות תפקידים. מריצים את הפקודה הבאה לכל אחד מהתפקידים הבאים ב-IAM:‏ roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent: 

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

      מחליפים את מה שכתוב בשדות הבאים:

      • SERVICE_ACCOUNT_NAME: השם של חשבון השירות
      • PROJECT_ID: מזהה הפרויקט שבו יצרתם את חשבון השירות
      • ROLE: התפקיד שאתם רוצים לתת

    4. מקצים את התפקיד הנדרש לחשבון המשתמש שיצרף את חשבון השירות למשאבים אחרים. 

      gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID. --member="principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/SUBJECT_ID" --role=roles/iam.serviceAccountUser

      מחליפים את מה שכתוב בשדות הבאים:

      • ‫SERVICE_ACCOUNT_NAME: השם של חשבון השירות.
      • PROJECT_ID: מזהה הפרויקט שבו יצרתם את חשבון השירות.
      • ‫POOL_ID: מזהה מאגר הזהויות של כוח העבודה.
      • ‫SUBJECT_ID: מזהה נושא, בדרך כלל המזהה של משתמש במאגר זהויות של כוח עבודה. למידע נוסף, קראו את המאמר ייצוג המשתמשים במאגרי כוח עבודה בכללי מדיניות IAM.
  8. סקירה כללית על ניראות של מיקרו-שירותים
  9. קוראים על שני משתני הסביבה הנתמכים, מחליטים באיזה מהם להשתמש ומגדירים את הערכים הנדרשים למשתנה הסביבה.

יצירה של מכונה וירטואלית ב-Compute Engine והתחברות אליה

כדי ליצור מכונה וירטואלית ב-Compute Engine ולהתחבר אליה, צריך לפעול לפי ההוראות הבאות. במכונה הווירטואלית פורסים את האפליקציה ואז מוסיפים לה יכולת תצפית על מיקרו-שירותים.

  1. יוצרים מכונה וירטואלית:

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

  2. מתחברים למופע של מכונה וירטואלית:

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

פריסת האפליקציה במכונה וירטואלית ב-Compute Engine

אתם יכולים לפרוס אפליקציה לבחירתכם במכונה הווירטואלית של Compute Engine שיצרתם בשלב הקודם, ואז לדלג על השלב הזה, או להשתמש בדוגמה כדי להמשיך עם ההוראות בשפה המועדפת עליכם.

C++‎

  1. אחרי שמתחברים למכונת ה-VM, מריצים את הפקודה הבאה.

    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

המשך

  1. מוודאים ש-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. משכפלים את הדוגמאות של gRPC-Go.

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

Java

  1. אחרי שמתחברים למכונה הווירטואלית, מוודאים שמותקנת בה גרסה 8 או גרסה עדכנית יותר של Java.

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

  2. משכפלים את מאגר grpc-java.

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

יצירת קובץ תצורה של תצפיתיות ב-gRPC Google Cloud

צריך קובץ תצורה נפרד של gRPC Google Cloud Observability כדי להפעיל ניראות של מיקרו-שירותים גם לשרת וגם ללקוח. המיקום של הקובץ הזה מיוצא כ-GRPC_GCP_OBSERVABILITY_CONFIG_FILE בשלבים הבאים. בהוראות הבאות מוסבר איך להגדיר את הפרמטרים השונים בקובץ תצורה.

דוגמה לערכים בשדה 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"
  }
}

בקטעים הבאים מוסבר איך להפעיל איסוף נתונים בהגדרות של הרכיבים השונים. אם השתמשתם בדוגמה ל-gRPC במדריך הזה, תוכלו להשתמש בהגדרה הזו כמו שהיא (אחרי עדכון של your-project-here) או להשתמש בה כתבנית לאפליקציה שלכם.בנוסף, יש כאן דוגמה שמציגה את פרטי ההגדרה במשתנה סביבה.

הפעלת המדדים

כדי להפעיל מדדים, מוסיפים את האובייקט cloud_monitoring להגדרות ומגדירים את הערך שלו ל-{}.

מידע נוסף על מדדים זמין במאמר הגדרות של מדדים.

הפעלת מעקב

כדי להפעיל את האפשרות 'מעקב':

  1. מוסיפים את האובייקט cloud_trace להגדרה.
  2. מגדירים את cloud_trace.sampling_rate ל-0.5 כדי לעקוב באופן אקראי אחרי 50% מה-RPC.

אם אתם מתכננים להפעיל מעקב בשירותים, ודאו שהשירותים תומכים בהפצה של הקשר יומן המעקב שהתקבל מה-upstream (או שהתחיל בעצמו) ל-downstream.

מידע נוסף על מעקב זמין במאמר הגדרות מעקב.

הפעלת הרישום ביומן

כדי להפעיל את רישום היומן:

  1. מוסיפים את האובייקט cloud_logging להגדרות האישיות.
  2. מוסיפים תבנית ל-client_rpc_events או ל-server_rpc_events, או לשניהם, ומציינים את קבוצת השירותים או השיטות שרוצים ליצור בשבילם רישום אירועים ברמת התעבורה, ואת מספר הבייטים שרוצים לרשום בשביל הכותרות וההודעות.

מידע נוסף על רישום ביומן זמין במאמר הגדרות של רשומות ביומן.

הוספת פלאגין הניראות לאפליקציות

כדי להטמיע את האפליקציות כך שיוכלו להשתמש בתוסף Microservices observability, פועלים לפי ההוראות הבאות בשפה המועדפת.

C++‎

אפשר להשתמש ב-C++‎ עם יכולת מעקב אחר מיקרו-שירותים החל מ-gRPC C++‎ v1.54. מאגר הדוגמאות נמצא ב-GitHub.

  1. התמיכה ב-Observability זמינה רק דרך מערכת ה-build של Bazel. מוסיפים את היעד grpcpp_gcp_observability כתלות.

  2. כדי להצטרף לתצפית על מיקרו-שירותים, צריך להוסיף תלות (מודול תצפית) ולבצע את השינויים הבאים בקוד של לקוחות gRPC, שרתי 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
}

    לפני כל פעולת gRPC, כולל יצירת ערוץ, שרת או פרטי כניסה, מפעילים את הפקודה הבאה:

    grpc::GcpObservability::Init();

    הפעולה הזו מחזירה את הערך absl::StatusOr<GcpObservability>, שצריך לשמור. הסטטוס עוזר לקבוע אם ההפעלה של יכולת התצפית בוצעה בהצלחה. האובייקט GcpObservability הנלווה שולט במשך החיים של הניראות (observability), וסוגר ומרוקן באופן אוטומטי את נתונים גלויים כשהוא יוצא מההיקף.

המשך

  1. יש תמיכה בתוספים של יכולת צפייה במיקרו-שירותים בגרסאות gRPC Go‏ v1.54.0 ואילך. המאגר לדוגמה נמצא ב-GitHub.

כדי להפעיל את התצפית על מיקרו-שירותים באמצעות מודול Go, צריך מודול תצפית ואת הקוד הבא:

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

הקריאה ל-observability.Start מנתחת את ההגדרות ממשתני הסביבה, יוצרת מייצאים בהתאם ומזריקה לוגיקת איסוף לחיבורי הלקוח ולשרתים שנוצרו אחרי הקריאה. הקריאה ל-deferredobservability.End מנקה את המשאבים ומוודאת שהנתונים במאגר הזמני נמחקים לפני שהאפליקציה נסגרת.

אחרי שמעדכנים את קוד האפליקציה, מריצים את הפקודה הבאה כדי לעדכן את הקובץ go.mod.

go mod tidy

Java

כדי להשתמש בניראות (observability) של מיקרו-שירותים באפליקציות Java, צריך לשנות את ה-build כך שיכלול את ארטיפקט grpc-gcp-observability. משתמשים ב-gRPC בגרסה 1.54.1 ואילך.

בקטעים בנושא יצירת קטעי קוד בכלי Gradle ובכלי Maven, הערך של grpcVersion מוגדר כ-1.54.1.

המאגר לדוגמה נמצא ב-GitHub.

  1. כדי להוסיף לאפליקציות ב-Java יכולת תצפית על מיקרו-שירותים, צריך להוסיף את הקוד הבא ל-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();
...
}

חשוב לזכור שצריך להפעיל את GcpObservability.grpcInit() לפני שיוצרים ערוצי gRPC או שרתים. הפונקציה GcpObservability.grpcInit() קוראת את הגדרות התצפית על מיקרו-שירותים, ומשתמשת בהן כדי להגדיר את ה-interceptors וה-tracers הגלובליים שנדרשים לתכונות הרישום ביומן, המדדים והמעקב בכל ערוץ ושרת שנוצרו. GcpObservability.grpcInit() is thread safe and must be called exactly once. היא מחזירה מופע של GcpObservability שצריך לשמור כדי להפעיל את close() מאוחר יותר.

‫GcpObservability.close() de-allocates resources. כל ערוץ או שרת שנוצרים לאחר מכן לא מבצעים רישום ביומן.

‫GcpObservability מטמיע את java.lang.AutoCloseable, שנסגר אוטומטית אם משתמשים בtry-with-resource באופן הבא:

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

אם משתמשים בכלי Gradle לבנייה, צריך לכלול את הקוד הבא:

def grpcVersion = '1.54.1'

...

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

שימוש בכלי ה-build של Maven‏ (pom.xml)

אם אתם משתמשים בכלי ה-build של Maven, צריך לכלול את הקוד הבא:

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

הפעלת האפליקציה

פועלים לפי ההוראות שבקטע הזה רק אם השתמשתם בדוגמה ל-gRPC במדריך. אפשר לשנות את הפקודה run כדי לטרגט את הקובץ הבינארי של האפליקציה.

הפעלת השרת

C++‎

  1. יוצרים סשן SSH במכונה הווירטואלית.

  2. מייצאים את משתני הסביבה. כדי ליצור את 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. מריצים את אפליקציית השרת shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server

המשך

  1. יוצרים סשן SSH למכונה הווירטואלית.

  2. מייצאים את משתני הסביבה. כדי ליצור את server_config.json, פועלים לפי השלבים שמפורטים למעלה.

    export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json

  3. מריצים את אפליקציית השרת shell go run ./server/main.go

Java

  1. בתיקיית הדוגמאות, פותחים את קובץ ה-README ופועלים לפי ההוראות שבו.
  2. כשההוראות אומרות לפתוח חלון טרמינל אחר, מפעילים את הפקודה הזו: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

לקוח הרצה

C++‎

  1. יוצרים סשן SSH נוסף למכונה הווירטואלית.

  2. ייצוא משתני סביבה. משתמשים בשלבים שמפורטים למעלה כדי ליצור קובץ 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. הפעלת אפליקציית הלקוח

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

המשך

  1. יוצרים סשן SSH נוסף למכונה הווירטואלית.
  2. מייצאים את משתני הסביבה. משתמשים בשלבים שמפורטים למעלה כדי ליצור קובץ client_config.json. shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json

  3. הפעלת אפליקציית הלקוח

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

Java

  1. בתיקיית הדוגמאות, פותחים את קובץ ה-README ופועלים לפי ההוראות שבו.
  2. כשההוראות אומרות לפתוח חלון טרמינל אחר, מריצים את הפקודה הבאה: shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

הסרת המשאבים

כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת המדריך הזה, אפשר למחוק את הפרויקט שמכיל את המשאבים או להשאיר את הפרויקט ולמחוק את המשאבים הנפרדים.

מחיקת הפרויקט

    כדי למחוק Google Cloud פרויקט:

    gcloud projects delete PROJECT_ID

מחיקת משאבים ספציפיים

  1. מוחקים את המכונה: 
    gcloud compute instances delete INSTANCE_NAME

המאמרים הבאים