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

במאמר הזה מוסבר איך נתוני מדדים שנשלחים ל Google Cloud פרויקט באמצעות Telemetry (OTLP) API ממופים למבנים של Cloud Monitoring. ה-API הזה מטמיע את פרוטוקול OpenTelemetry. אפשר לשלוח נתונים ל-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, צריך גם:

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

  • מקצים למשתמש או לחשבון השירות שבו האפליקציה משתמשת את התפקידים הבאים בניהול הזהויות והרשאות הגישה (IAM):

    • התפקיד Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) בפרויקט של מכסת השימוש.
    • התפקיד Cloud Telemetry Writer‏ (roles/telemetry.writer) בפרויקט. התפקיד הזה מאפשר לאפליקציה לכתוב נתונים של יומנים, מדדים ומעקב.

מדדי 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__, אם מאפיין cloud.platform הוא gcp_compute_engine
  • ‫__run__, אם מאפיין cloud.platform הוא gcp_cloud_run
  • ‫__vae__, אם מאפיין cloud.platform הוא 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 point kind מעקב אחרי סוג המדד מעקב אחרי סוג הערך סיומת הערות
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  
היסטוגרמה אקספוננציאלית (מצטברת) מצטבר הפצה עם קטגוריות מעריכיות /histogram  
היסטוגרמה (דלתא) DELTA DISTRIBUTION with explicit buckets /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.

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

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

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

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

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

מכסות

מידע על מכסות שקשורות ל-Telemetry API זמין במאמר מגבלות של Telemetry API.