סקירה כללית של מדדים בגרסה 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
  • מחרוזת ריקה
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 gauge.
  • ‫OTLP Sum ממופה באופן הבא:
    • למדד gauge של Cloud Monitoring כשis_monotonic מוגדר ל-false.
    • ל-Cloud Monitoring cumulative כש-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 עם זמניות דלתא.
היסטוגרמה (מצטברת) מצטבר DISTRIBUTION with explicit buckets /histogram  
היסטוגרמה אקספוננציאלית (מצטברת) מצטבר ‫DISTRIBUTION עם קטגוריות מעריכיות /histogram  
היסטוגרמה (דלתא) DELTA DISTRIBUTION with explicit buckets /histogram:delta  
היסטוגרמה אקספוננציאלית (דלתא) DELTA ‫DISTRIBUTION עם קטגוריות מעריכיות /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 לייצוא ממיר את כל המופעים של התווים האלה לתו קו תחתון (_). לדוגמה, מדד 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.