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

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

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

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

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

בצעו אינסטרומנטציה לאפליקציה שלכם כדי לאסוף מידע ספציפי שיעזור לכם להבין את הביצועים שלה ולפתור בעיות. יש כמה מסגרות עבודה של מכשור בקוד פתוח שאוספות נתונים של יומנים, מדדים ועקבות, ויכולות לשלוח את הנתונים האלה לכל ספק, כולל 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) כדי לאסוף עקבות ומדדים מהאפליקציה. סוכן תפעול יכול גם לאסוף יומנים, אבל לא באמצעות OTLP. מידע נוסף זמין במאמרים שימוש בסוכן תפעול וב-OTLP ובסקירה כללית על סוכן תפעול.

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

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

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

דוגמאות של אינסטרומנטציה

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

יצירת טווחים בהתאמה אישית

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

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

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

אילוץ דגימה של מעקב

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

  • האפליקציות שלכם: אתם מגדירים איך לוגיקת המדידה מתייחסת לדגל sampled. לדוגמה, כשמשתמשים ב-OpenTelemetry, אפשר להשתמש ב-ParentBased sampler כדי לוודא שדגל הדגימה של הרכיב ההורה נשמר.

  • ‫Google Cloud services: כל שירות קובע את התמיכה שלו במעקב. באופן כללי, השירותים מקבלים את דגל הדגימה של ההורה כרמז, תוך שהם אוכפים את מגבלות קצב הדגימה שלהם.

השוואה בין מדדים ועקבות עם נתונים מייצגים

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

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

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

בקטע הזה מפורטים ממשקי ה-API והתפקידים בניהול הזהויות והרשאות הגישה (IAM) שנדרשים, ומוסבר איך להגדיר את פרטי האימות של הפלטפורמה.

הפעלת ממשקי ה-API

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

מפעילים את ממשקי ה-API של טלמטריה ו-Cloud Trace.

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

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

הפעלת ממשקי ה-API

מתן תפקידים ב-IAM

תפקידי ה-IAM הנדרשים תלויים בשיטה שבה אתם משתמשים כדי לראות את נתוני המעקב: במסוף Google Cloud או בכתיבת נתוני המעקב לפרויקט.

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

  • כדי לקבל את ההרשאות שדרושות לכתיבת נתוני מעקב באמצעות Cloud Trace API, צריך לבקש מהאדמין להקצות לכם את התפקיד Cloud Trace Agent (roles/cloudtrace.agent) ב-IAM בפרויקט.

  • כדי לקבל את ההרשאות שנדרשות לכתיבת נתוני מעקב באמצעות Telemetry API, צריך לבקש מהאדמין להקצות לכם את התפקיד Cloud Telemetry Writer (roles/telemetry.writer) ב-IAM בפרויקט.

אמת

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

ריצה ב- Google Cloud

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

מוודאים ש Google Cloud בפלטפורמה שלכם מופעל היקף הגישה של Cloud Trace API. בהגדרות הבאות, הגדרות ברירת המחדל של היקף הגישה כוללות את היקף הגישה של Cloud Trace API:

אם אתם משתמשים בהיקפי גישה בהתאמה אישית, אתם צריכים לוודא שהיקף הגישה של 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 Google Cloud, אתם צריכים לספק פרטי אימות לספריית הלקוח. צריך להעניק לחשבון השירות את התפקיד Cloud Trace Agent ‏(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"

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