הגדרת מעקב ב-Cloud Trace

במאמר הזה מוסבר בקצרה איך להטמיע את Cloud Trace באפליקציה. הוראות מפורטות להגדרת Cloud Trace מופיעות בדפי ההגדרה הספציפיים לשפה.

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

מתי כדאי להוסיף לאפליקציה קוד למעקב

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

אם נתוני המעקב לא נאספים באופן אוטומטי כדי לאמת את הביצועים או לפתור בעיות, צריך להגדיר את האפליקציה.

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

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

איך מטמיעים כלי מדידה באפליקציות

יש כמה גישות שבהן אפשר להשתמש כדי להטמיע את האפליקציה:

• מומלץ: משתמשים ב-OpenTelemetry, מגדירים את האפליקציה באמצעות OTLP exporter ששולח נתוני מעקב אל collector, ומגדירים את ה-collector כך שישלח נתוני מעקב אל פרויקט Google Cloud באמצעות Telemetry (OTLP) API. מידע נוסף על ההמלצות שלנו

• משתמשים ב-OpenTelemetry ומגדירים את האפליקציה באמצעות OTLP exporter ששולח את נתוני המעקב לפרויקט Google Cloud באמצעות Telemetry API.

• אם אתם כותבים אפליקציות שפועלות ב-Compute Engine, אתם יכולים להשתמש בסוכן התפעול ובמקלט של פרוטוקול OpenTelemetry ‏ (OTLP) כדי לאסוף עקבות ומדדים מהאפליקציה. הסוכן Ops יכול גם לאסוף יומנים, אבל לא באמצעות OTLP. מידע נוסף זמין במאמרים שימוש בסוכן תפעול וב-OTLP ובסקירה כללית על סוכן תפעול.

• להפעיל ישירות את Telemetry API או את Cloud Trace API.

• משתמשים בספריות הלקוח של Cloud Trace או ב-Cloud Trace exporter ל-OpenTelemetry.

• באפליקציות Spring Boot, צריך להגדיר את האפליקציות כך שיעבירו את נתוני המעקב שהן אוספות אל Cloud Trace. מידע על התהליך הזה זמין במאמר בנושא Spring Cloud for Google Cloud: Cloud Trace.

הדוגמאות של שדרוג המידע שאנחנו מספקים משתמשות ב-OpenTelemetry:

• דוגמאות לשימוש בייצוא מבוסס-איסוף:

  • Go
  • Java
  • Node.js
  • Python

  הדוגמאות האלה שולחות נתוני מעקב אל Telemetry API.

• במאמר מעבר מייצוא נתוני מעקב לנקודת הקצה של OTLP מוסבר איך להשתמש בייצוא ישיר של נתוני מעקב ולשלוח את הנתונים האלה ל-Telemetry API.

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

• במאמר בדיקת קריאות ל-MCP באמצעות Trace מוסבר אילו שרתי MCP מרוחקים של Google Cloud תומכים ביצירת עקבות, ואיך להגדיר את האפליקציה כך שתורה לשרתים האלה ליצור טווחים.

מתי כדאי ליצור טווחים

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

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

מתי צריך לספק פרטי כניסה לאימות

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

אם אתם מריצים את האפליקציה מחוץ ל- Google Cloud, אתם צריכים לספק לה פרטי אימות. צריך גם לציין את מזהה הפרויקטGoogle Cloud באפליקציה.

פרטים נוספים זמינים בדפי ההגדרה לפי שפה.

איך מאלצים מעקב אחר בקשה

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

לגבי רכיבים במורד הזרם שהקוד שלהם בבעלותכם, אתם צריכים לקבוע אם לוגיקת המכשור שלכם מכבדת את הדגל sampled. לדוגמה, כשמשתמשים ב-OpenTelemetry למדידה, אפשר להשתמש ב-ParentBased sampler כדי לוודא שהדגל של הדגימה של הרכיב ההורה נשמר.

Google Cloud שירותים שמתעדים מידע על מעקב ב-Cloud Trace בדרך כלל מקבלים את דגל הדגימה של ההורה כרמז, אבל רוב השירותים גם מגבילים את קצב הדגימה. כל Google Cloud שירות קובע אם הוא תומך במעקב, איך נעשה שימוש בדגל הדגימה של ההורה ואת הגבלת הקצב של הדגימה.

איך מבצעים קורלציה בין נתוני מדדים לבין נתוני מעקב

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

הגדרת הפרויקט והפלטפורמה

1. מוודאים ש-Cloud Trace API מופעל.

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

   מפעילים את Cloud Trace API.

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

   כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

   להפעלת ה-API

2. מגדירים את הפלטפורמה.

   אפשר להשתמש ב-Cloud Trace ב- Google Cloud ובפלטפורמות אחרות.

   • ‫Google Cloud: כשהאפליקציה פועלת ב-Google Cloud, לא צריך לספק לספריית הלקוח פרטי אימות בצורה של חשבון שירות. עם זאת, צריך לוודא שלפלטפורמה שלכם יש היקף גישה ל-Cloud Trace API מופעל. Google Cloud

     בהגדרות הבאות, הגדרות ברירת המחדל של היקף הגישה כוללות את היקף הגישה של Cloud Trace API:

     • Compute Engine

     • Google Kubernetes Engine (GKE)‎

       הערה: אם אתם משתמשים ב-Autopilot או אם הפעלתם את התכונה 'איחוד זהויות של עומסי עבודה ל-GKE' באשכול GKE, עליכם לוודא שהגדרתם את האפליקציה כך שתשתמש בתכונה 'איחוד זהויות של עומסי עבודה ל-GKE'.

     • הסביבה הגמישה של App Engine

     • הסביבה הסטנדרטית של App Engine

     • Cloud Run

     אם אתם משתמשים בהיקפי הרשאות בהתאמה אישית, אתם צריכים לוודא שהיקף ההרשאות של Cloud Trace API מופעל. לדוגמה, אם משתמשים ב-Google Cloud CLI כדי ליצור אשכול GKE ומציינים את הדגל --scopes, צריך לוודא שההיקף כולל את trace.append. הפקודה הבאה מדגימה איך מגדירים את הדגל --scopes:

     gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

   • הפעלה באופן מקומי ובמקומות אחרים: אם האפליקציה שלכם פועלת מחוץ ל-Google Cloud, אתם צריכים לספק לספריית הלקוח פרטי כניסה לאימות בצורה של חשבון שירות. צריך להקצות לחשבון השירות את התפקיד של סוכן Cloud Trace ‏(roles/cloudtrace.agent). מידע על תפקידים מופיע במאמר שליטה בגישה באמצעות IAM.

     Google Cloud ספריות הלקוח משתמשות ב-Application Default Credentials ‏ (ADC) כדי למצוא את פרטי הכניסה של האפליקציה. יש שלוש דרכים לספק את פרטי הכניסה האלה:

     • מריצים את gcloud auth application-default login

     • ממקמים את חשבון השירות בנתיב ברירת מחדל למערכת ההפעלה. ברשימה הבאה מפורטות נתיבי ברירת המחדל ל-Windows ול-Linux:

       • ב-Windows:‏ %APPDATA%/gcloud/application_default_credentials.json‎

       • ‫Linux: ‏ $HOME/.config/gcloud/application_default_credentials.json

     • מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב של חשבון השירות:

       ‫Linux/macOS

         export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

       Windows

         set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

       ‫PowerShell:

         $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

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

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

• דוגמאות לשימוש ב-OpenTelemetry:

  • דוגמה ל-Python

  • דוגמה ל-Java

  • דוגמה ל-Node.js

  • לדגום

  • דוגמה ל-C++‎