סקירה כללית של מדדים בגרסה 1

במאמר הזה מוסבר איך נתוני מדדים שנשלחים לפרויקט Google Cloud שלכם באמצעות Telemetry (OTLP) API ממופים למבנים של Cloud Monitoring. ה-API הזה מטמיע את OpenTelemetry Line Protocol. אפשר לשלוח נתונים ל-API הזה כשמגדירים את האפליקציות באמצעות otlphttp exporter ו-OpenTelemetry Collector, או כשמשתמשים ב-OpenTelemetry SDKs.

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

שיטות מומלצות

כשמגדירים את האפליקציות לשליחת נתוני מעקב אלGoogle Cloud הפרויקט, מומלץ להשתמש בכלי לייצוא שכותב נתונים בפורמט OTLP אל Collector, ששולח את נתוני המעקב אל Telemetry API. בכלי לאיסוף נתונים, מציינים רק את כתובת ה-URL הבסיסית:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

‫OpenTelemetry מזהה את סוג הנתונים ומצרף באופן אוטומטי את /v1/traces,‏ /v1/metrics או /v1/logs לפי הצורך. מידע נוסף אפשר למצוא במאמר בנושא OTLP/HTTP Request.

דוגמאות לייצוא נתוני מעקב או מדדים אל Telemetry API זמינות במסמכים הבאים:

אם אתם לא יכולים להשתמש ב-Collector, אתם יכולים להשתמש בספריית OpenTelemetry שמכילה רכיב OTLP exporter בתוך התהליך כדי לשלוח נתוני טלמטריה ל-Telemetry API. במאמר ייצוא נתוני מעקב לנקודת הקצה של OTLP מוסבר איך לייצא נתוני מעקב ישירות.

אימות

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

דוגמה לאימות כשמשתמשים בייצוא ישיר של נתוני מעקב מופיעה במאמר בנושא הגדרת אימות. בדוגמה הזו מוסבר איך להגדיר את כלי הייצוא באמצעות Google Cloud Application Default Credentials ‏ (ADC) ולהוסיף לאפליקציה ספריית אימות של Google שספציפית לשפה.

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

  • הגדרה של פרויקט לצורכי מכסה. מידע נוסף זמין במאמר בנושא הגדרת פרויקט לצורכי מכסה.
  • נותנים למשתמש או לחשבון השירות שהאפליקציה משתמשת בו את התפקיד Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) בפרויקט של הקצאת המכסות.

  • מעניקים למשתמש או לחשבון השירות שהאפליקציה משתמשת בו את התפקידים הבאים בפרויקט:

מדדי OTLP ב-Cloud Monitoring

כשמדדים מוזנים ל-Cloud Monitoring באמצעות OpenTelemetry Collector ו-otlphttp exporter, או נשלחים ישירות באמצעות OpenTelemetry SDK, המדדים של OTLP ממופים למבני מדדים של Cloud Monitoring. בקטע הזה מתוארים הנושאים הבאים:

מיפוי של משאבים במעקב

כל נקודות המדדים נכתבות כמו בשירות המנוהל של Google Cloud ל-Prometheus, באמצעות מיפוי Prometheus.

מיפוי Prometheus

מדדי Prometheus מחייבים שימוש בסוג המשאב המנוטר prometheus_target.

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

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

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

התווית prometheus-target הערך שבו נעשה שימוש (לפי סדר העדיפות)
location (חובה)
  • מאפיין location
  • מאפיין cloud.availability_zone
  • מאפיין cloud.region
  • דחיית הנקודה אם היא ריקה
cluster
  • מאפיין cluster
  • מאפיין k8s.cluster.name
  • ‫__gce__, if cloud.platform attribute is gcp_compute_engine
  • ‫__run__, if cloud.platform attribute is gcp_cloud_run
  • ‫__vae__, if cloud.platform attribute is gcp.agent_engine
  • מחרוזת ריקה
namespace
  • מאפיין namespace
  • מאפיין k8s.namespace.name
  • מאפיין service.namespace
  • מחרוזת ריקה
job
  • מאפיין job
  • ‫"service.namespace" + "/" + מאפיין service.namespace
  • מאפיין service.name
  • service.name, if not unknown_service:foo
  • מאפיין faas.name
  • מאפיין k8s.deployment.name
  • מאפיין k8s.statefulset.name
  • מאפיין k8s.job.name
  • מאפיין k8s.cronjob.name
  • service.name attribute, if unknown_service:foo
  • מחרוזת ריקה
instance (חובה)
  • מאפיין instance
  • מאפיין service.instance.id
  • מאפיין faas.instance
  • מאפיין k8s.pod.name:k8s.container.name
  • מאפיין k8s.pod.name, אם לא צוין שם של קונטיינר
  • מאפיין host.id
  • דחיית הנקודה אם היא ריקה

מיפוי מדדים

המדדים מומרים לפורמט של סדרת זמן של Prometheus. שמות המדדים לא יכולים לכלול דומיין או שהדומיין צריך להיות prometheus.googleapis.com. אחרי ההמרה, שם המדד יכלול את הקידומת prometheus.googleapis.com ותוספת סיומת, בהתאם לסוג הנקודה של OTLP. למדד שמתקבל ב-Cloud Monitoring יש את המבנה הבא:

prometheus.googleapis.com/{metric_name}/{suffix}

בנוסף, לכל משאב ייחודי של OpenTelemetry, ההמרה מוסיפה מדד target_info שמכיל את כל מאפייני המשאב, למעט service.name, service.instance.id ו-service.namespace.

כל המדדים של OTLP INT64 מתורגמים לסוג הערך DOUBLE ב-Cloud Monitoring, גם אם האוסף מציין את סוג הערך כ-INT64. השינוי הזה מתבצע כי אחרי שמכניסים סדרת נתונים כרונולוגית ל-Monarch, אי אפשר לשנות את סוג הערך. התוצאה הנפוצה ביותר של תמיכה בערכים של INT64 היא שמתקבלים התנגשויות שאפשר לפתור רק על ידי מחיקת מדד.

מיפוי מדדים של Prometheus

המיפוי של סוגי המדדים הוא כזה:

  • מדד OTLP Gauge ממופה למדד ב-Cloud Monitoring.
  • ‫OTLP Sum ממופה באופן הבא:
    • למדד gauge של Cloud Monitoring כשis_monotonic מוגדר ל-false.
    • ל-Cloud Monitoring מצטבר כאשר aggregation_temporality מוגדר לערך AGGREGATION_TEMPORALITY_CUMULATIVE.
    • ל-Cloud Monitoring delta כש-aggregation_temporality מוגדר לערך AGGREGATION_TEMPORALITY_DELTA.
  • היסטוגרמה של OTLP ממופה להתפלגות ב-Cloud Monitoring עם סוג מדד של cumulative או delta, בהתאם לערך של aggregation_temporality.
  • מדדי הסיכום של OTLP מורחבים לסדרות זמן נפרדות לכל רכיב: count,‏ sum וכל quantile.
    • השמות של מדדי הספירה והסכום מסתיימים ב-_count או ב-_sum בהתאמה, והם כתובים כמדדים מצטברים של Cloud Monitoring מסוג DOUBLE.
    • כל קוונטיל הופך לסדרת זמן משלו של מדד מסוג DOUBLE, עם תווית quantile.

בטבלה הבאה מפורט מיפוי המדדים:

סוג הנקודה ב-OTLP מעקב אחרי סוג המדד מעקב אחרי סוג הערך סיומת הערות
GAUGE GAUGE DOUBLE /gauge  
‫GAUGE (metric.metadata["prometheus.type"]="unknown") GAUGE DOUBLE /unknown המדדים של Prometheus Unknowns מחולקים למונה ולמדד על ידי OpenTelemetry Collector.
SUM (monotonic, CUMULATIVE) מצטבר DOUBLE /counter  
SUM (monotonic, CUMULATIVE, metric.metadata["prometheus.type"]="unknown") מצטבר DOUBLE /unknown:counter המדדים של Prometheus Unknowns מחולקים למונה ולמדד על ידי OpenTelemetry Collector.
SUM (monotonic, DELTA) DELTA DOUBLE /delta  
SUM (non-monotonic, CUMULATIVE) GAUGE DOUBLE /gauge  
SUM (non-monotonic, DELTA) לא נתמך אין תמיכה ב-UpDownCounters עם זמניות דלתא.
היסטוגרמה (מצטברת) מצטבר הפצה עם קטגוריות תוכן בוטה /histogram  
היסטוגרמה אקספוננציאלית (מצטברת) מצטבר הפצה עם קטגוריות מעריכיות /histogram  
היסטוגרמה (דלתא) DELTA הפצה עם קטגוריות תוכן בוטה /histogram:delta  
היסטוגרמה אקספוננציאלית (דלתא) DELTA הפצה עם קטגוריות מעריכיות /histogram:delta  
SUMMARY
(sum,
count,
quantile)		  
מצטבר
מצטבר
מד		  
DOUBLE
DOUBLE
DOUBLE		  
_sum/summary:counter
_count/summary
/summary		 נקודות הנתונים של הסיכום נכתבות כסדרות זמן מרובות, אחת לכל ספירה, סכום וקוונטיל מחושב. מדדי הכמותיים נוצרים גם הם עם התווית quantile.

ההבדלים בין כלי הייצוא googlemanagedprometheus לבין Telemetry API

ה-Telemetry API‏ (telemetry.googleapis.com) מטפל במדדים באופן שונה מgooglemanagedprometheus exporter:

  • ב-Telemetry API אפשר להשתמש בנקודה (.) ובסלאש (/) בשמות של מדדים. הפונקציה googlemanagedprometheus exporter ממירה את כל המופעים של התווים האלה לתו קו תחתון (_). לדוגמה, מדד OTLP בשם prometheus.googleapis.com/foo.bar/gauge מיוצא כלשונו על ידי כלי הייצוא של OTLP, אבל מיוצא בתור prometheus.googleapis.com/foo_bar/gauge על ידי כלי הייצוא googlemanagedprometheus.

    כשמבצעים הטמעה של המדדים, Cloud Monitoring יוצר מתארי מדדים על סמך השמות. ההבדל באופן הטיפול בנקודה (.) ובקו נטוי (/) בנתיבי ההטמעה גורם לכך שמתארי המדדים שמתקבלים שונים בין מדדים שהוטמעו באמצעות כלי הייצוא googlemanagedprometheus לבין מדדים שהוטמעו באמצעות כלי הייצוא otlphttp. אם משתמשים בשני נתיבי ההטמעה, מקבלים שני סטים של מדדים. כדי לקבל תוצאות מלאות כשמריצים שאילתה, צריך לאחד באופן ידני את התוצאות מהגרסאות של המדדים ב-Prometheus וב-OTLP.

  • ‫Telemetry API לא מוסיף יחידה לשם של מדד אם יש יחידה, והוא לא מוסיף את הסיומת _total למונים. לכן, מדד שמיוצא כ-prometheus.googleapis.com/foo/counter כשמשתמשים ב-Telemetry API מיוצא כ-prometheus.googleapis.com/foo_seconds_total/counter על ידי googlemanagedprometheus exporter. ההבדל הזה רלוונטי גם לסיומות _total ו-_ratio.

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

  • ה-API ממיר את כל ערכי הנקודות של מספרים שלמים לערכים כפולים של מדדי Prometheus.

  • ה-API לא מגדיר את התוויות scope_version או scope_name אם הערכים שלהן ריקים.

Cloud Monitoring ומיקום אחסון הנתונים

מידע על האופן שבו נתוני המדדים מאוחסנים זמין במאמר בנושא אזוריות הנתונים ב-Cloud Monitoring.

איפה אפשר לראות את הנתונים שהועברו

אפשר לראות את נתוני המדדים שמוטמעים דרך Telemetry API בדף Metrics Explorer. מידע על צפייה בנתוני המדדים ויצירת תרשימים שלהם זמין במאמר יצירת תרשימים באמצעות Metrics Explorer.