‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שאילתה והצגה של מדדים

אחרי שאוספים מדדים מעומסי העבודה שנפרסו ב-Google Distributed Cloud (GDC)‎ עם air gap, אפשר להתחיל לנתח אותם. כדי לנתח מדדים, אתם יכולים להציג אותם באופן חזותי ולסנן אותם במרכזי בקרה אינפורמטיביים של Grafana, או לגשת אליהם ישירות מ-Cortex באמצעות הכלי curl לכתיבת סקריפטים גמישים ולאוטומציה.

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

יש שתי דרכים לגשת למדדים:

מרכזי בקרה של Grafana: בחינת מגמות וזיהוי חריגות באמצעות תצוגות חזותיות אינטואיטיביות של מדדים חשובים, כמו ניצול המעבד (CPU), צריכת האחסון והפעילות ברשת. ב-Grafana יש ממשק ידידותי למשתמש שמאפשר לסנן ולנתח את נתוני עומסי העבודה במרכזי בקרה.
נקודת קצה של Cortex: בתרחישי שימוש מתקדמים יותר, אפשר לשלוח שאילתות ישירות למכונה של Cortex בפרויקט באמצעות הכלי curl בשורת הפקודה. ב-Cortex נשמרים מדדי Prometheus של הפרויקט, והוא מספק נקודת קצה (endpoint) ב-HTTP לגישה פרוגרמטית. הגישה הזו מאפשרת לכם לייצא נתונים, להפוך משימות לאוטומטיות וליצור שילובים בהתאמה אישית.

לפני שמתחילים

כדי לקבל את ההרשאות שנדרשות לשליחת שאילתות ולהצגת מדדים בלוחות הבקרה של Grafana, צריך לבקש ממנהל החשבון הארגוני או ממנהל הפרויקט ב-IAM להקצות לכם את אחד מהתפקידים המוגדרים מראש: "צפייה ב-Grafana ברמת הארגון" או "צפייה ב-Grafana ברמת הפרויקט". בהתאם לרמת הגישה וההרשאות שאתם צריכים, אתם יכולים לקבל תפקידים של Grafana בארגון או בפרויקט.

לחלופין, כדי לקבל את ההרשאות שנדרשות לשליחת שאילתות על מדדים מנקודת הקצה של Cortex, צריך לבקש מהאדמין של הפרויקט ב-IAM להקצות לכם את התפקיד Project Cortex Prometheus Viewer במרחב השמות של הפרויקט.

בטבלה הבאה מפורטות הדרישות של Role לגבי המשתמשים בתפקידי PA ו-AO.

פרסונה	אובייקט	אשכול	תפקיד	מרחב שמות	קבוצה/משתמש	הגדרה
PA	grafana	מנהל חשבון ארגוני	`project-grafana-viewer`	platform-obs	קבוצה	1
PA	cortex	מנהל חשבון ארגוני	`project-cortex-prometheus-viewer`	platform-obs	קבוצה	2
PA	grafana	מנהל חשבון ארגוני	`project-grafana-viewer`	platform-obs	משתמש	3
PA	cortex	מנהל חשבון ארגוני	`project-cortex-prometheus-viewer`	platform-obs	משתמש	4
AO	grafana	מנהל חשבון ארגוני	`project-grafana-viewer`	PROJECT_NAMESPACE	קבוצה	1
AO	cortex	מנהל חשבון ארגוני	`project-cortex-prometheus-viewer`	PROJECT_NAMESPACE	קבוצה	2
AO	grafana	מנהל חשבון ארגוני	`project-grafana-viewer`	PROJECT_NAMESPACE	משתמש	3
AO	cortex	מנהל חשבון ארגוני	`project-cortex-prometheus-viewer`	PROJECT_NAMESPACE	משתמש	4

מחליפים את המשתנים הבאים בהתאם:

משתנה	תיאור
`KUBECONFIG`	תצטרכו את ה-kubeconfig של האשכול הספציפי שמכיל את ה-`NAMESPACE` שבו יחול ה-RoleBinding הזה.
`RULE_NAME`	השם הייחודי של המשאב `RoleBinding` במרחב השמות. לדוגמה, `io-root-cortex-prometheus-viewer`.
`NAMESPACE`	מרחב השמות של Kubernetes שבו ייווצר ויחול ה-`RoleBinding` הזה. חפשו את העמודה `Namespace` בטבלה הקודמת.
`EMAIL_ADDRESS`	המזהה של המשתמש שמקבל את התפקיד. לרוב מדובר בכתובת אימייל. לדוגמה, `infrastructure-operator@example.com`.
`ROLE`	השם של ה-`Role` שמכיל את ההרשאות שרוצים לתת למשתמש. מחפשים את התפקידים שזמינים בטבלה הקודמת.
`GROUP_NAME`	השם של `Group` שהמשתמש עם הרשאת PA או AO שייך אליו. לדוגמה, `pa-group`.
`ZONE`	שם האזור

הגדרה 1

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

פקודת Kubectl

זהו הפורמט הכללי של הפקודה:

kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-grafana-viewer

לדוגמה:

kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs

נתיב קובץ IAC

/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>

קובץ YAML

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: Group
  name: GROUP_NAME
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

הגדרה 2

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

פקודת Kubectl

זהו הפורמט הכללי של הפקודה:

kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-cortex-prometheus-viewer

לדוגמה:

kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --group=my-team --namespace=platform-obs

נתיב קובץ IAC

/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>

קובץ YAML

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: Group
  name: GROUP_NAME
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-cortex-prometheus-viewer
  apiGroup: rbac.authorization.k8s.io

הגדרה 3

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

פקודת Kubectl

זהו הפורמט הכללי של הפקודה:

kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-grafana-viewer

לדוגמה:

kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obs

נתיב קובץ IAC

/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>

קובץ YAML

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: User
  name: EMAIL_ADDRESS
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

הגדרה 4

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

פקודת Kubectl

זהו הפורמט הכללי של הפקודה:

kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-cortex-prometheus-viewer

לדוגמה:

kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --user=my-email@example.com --namespace=platform-obs

נתיב קובץ IAC

/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>

קובץ YAML

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: User
  name: EMAIL_ADDRESS
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-cortex-prometheus-viewer
  apiGroup: rbac.authorization.k8s.io

למידע נוסף על התפקידים האלה, ראו הכנת הרשאות IAM.

איך מקבלים ומסננים את המדדים

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

מרכזי בקרה של Grafana

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

זיהוי נקודת הקצה (endpoint) של Grafana

כתובת ה-URL הבאה היא נקודת הקצה של המכונה של Grafana בפרויקט:

  https://GDC_URL/PROJECT_NAMESPACE/grafana

מחליפים את מה שכתוב בשדות הבאים:

‫GDC_URL: כתובת ה-URL של הארגון ב-GDC.
‫PROJECT_NAMESPACE: מרחב השמות של הפרויקט.

לדוגמה, נקודת הקצה של Grafana לפרויקט platform-obs בארגון org-1 היא https://org-1/platform-obs/grafana.

הצגת מדדים בממשק המשתמש של Grafana

אחזור מדדים בממשק המשתמש של Grafana:

בוחרים את הפרויקט במסוף GDC.
בתפריט הניווט, לוחצים על Operations > Monitoring.
לוחצים על View all in Grafana.

דף חדש פותח את נקודת הקצה של Grafana ומציג את ממשק המשתמש.
בתפריט הניווט בממשק המשתמש, לוחצים על explore Explore כדי לפתוח את הדף Explore.
בתפריט שבסרגל Explore, בוחרים מקור נתונים כדי לאחזר מדדים, בהתאם לסוג היקום:
- אשכולות עם אזור אחד: בוחרים באפשרות prometheus כדי להציג מדדים מהאזור היחיד של האשכול.
- סביבות עם כמה אזורים: Grafana יכולה להתחבר לאזורים שונים ולהציג נתונים מאזורים שונים. בוחרים באפשרות Metrics ZONE_NAME כדי להציג מדדים מכל אזור ב-Universe, בלי קשר לאזור שאליו נכנסתם.
  
  בנוסף, כדי להציג נתונים חזותיים מאזורים שונים במרכז בקרה אחד ולהוסיף כמה אזורים לשאילתה, בוחרים באפשרות Mixed כמקור הנתונים.
מזינים שאילתה כדי לחפש מדדים באמצעות ביטויי PromQL (שפת השאילתות של Prometheus). אפשר לבצע את השלב הזה באחת מהדרכים הבאות:
- בוחרים מדד ותווית לשאילתה בתפריטים Metric ו-Label filters. לוחצים על add Add כדי להוסיף עוד תוויות לשאילתה. אחר כך לוחצים על Run query.
- מזינים את השאילתה ישירות בשדה הטקסט Metrics ולוחצים על Shift+Enter כדי להריץ את השאילתה.
בדף מוצגים המדדים שתואמים לשאילתה.

איור 1. אפשרות בתפריט לשליחת שאילתות לגבי מדדים מממשק המשתמש של Grafana.

באיור 1, האפשרות prometheus מציגה את הממשק שמאפשר ליצור שאילתות מ-Grafana כדי לאחזר מדדים.

במאמר שאילתות ותוויות לדוגמה מפורטות דוגמאות לערכים של תוויות שאפשר להשתמש בהם כדי לשלוח שאילתות לגבי מדדים.

נקודת קצה של Cortex – אזור אחד

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

זיהוי נקודת הקצה של Cortex

כתובת ה-URL הבאה היא נקודת הקצה של המכונה של Cortex בפרויקט:

  https://GDC_URL/PROJECT_NAMESPACE/cortex/prometheus/

מחליפים את מה שכתוב בשדות הבאים:

‫GDC_URL: כתובת ה-URL של הארגון ב-GDC.
‫PROJECT_NAMESPACE: מרחב השמות של הפרויקט.

לדוגמה, נקודת הקצה של Cortex לפרויקט platform-obs בארגון org-1 היא https://org-1/platform-obs/cortex/prometheus/.

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

אימות הבקשה של `curl`

מורידים ומתקינים את ה-CLI של gdcloud.
מגדירים את המאפיין gdcloud core/organization_console_url:
```
gdcloud config set core/organization_console_url
https://GDC_URL
```
נכנסים לחשבון באמצעות ספק הזהויות שהוגדר:
```
gdcloud auth login
```
משתמשים בשם המשתמש ובסיסמה כדי לאמת את החשבון ולהיכנס אליו.

אחרי ההתחברות, אפשר להשתמש בכותרת ההרשאה בבקשת ה-curl באמצעות הפקודה gdcloud auth print-identity-token. מידע נוסף זמין במאמר gdcloud auth.

שליחת קריאה לנקודת הקצה של Cortex

כדי להגיע לנקודת הקצה של Cortex באמצעות הכלי curl:

מאמתים את הבקשה של curl.
משתמשים ב-curl כדי לשלוח קריאה לנקודת הקצה של Cortex ומרחיבים את כתובת ה-URL באמצעות פורמט השאילתות של HTTP API כדי לשלוח שאילתות לגבי מדדים.

דוגמה לבקשת curl:
```
curl https://GDC_URL/PROJECT_NAME/cortex/prometheus/api/v1/query?query=my_metric{cluster="my-cluster"}&time=2015-07-01T20:10:51.781Z \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"
```
הפלט מתקבל אחרי הפקודה. התגובה מה-API היא בפורמט JSON.

הערה: צריך להוסיף את נקודת הקצה api/v1/query כדי לשלוח שאילתות לגבי מדדים מכתובת ה-URL. אפשר לכלול פרמטרים אופציונליים לקריאה ל-API אחרי סימן שאלה (?) בסוף כתובת ה-URL. מפרידים בין הפרמטרים האלה באמצעות סמלי אמפרסנד (&), כמו בדוגמה של הבקשה curl מהשלב הקודם.

נקודת קצה של Cortex – כמה אזורים

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

זיהוי נקודת הקצה של Cortex

כתובת ה-URL הבאה היא נקודת הקצה של המכונה של Cortex בפרויקט שלכם לשאילתה בכמה אזורים:

  https://GDC_URL/PROJECT_NAMESPACE/cortex/metrics

מחליפים את מה שכתוב בשדות הבאים:

‫GDC_URL: כתובת ה-URL של הארגון ב-GDC.
- דוגמה ל-org-1, zone1: console.org-1.zone1.google.gdch.test
- מחליפים את הארגון והאזור של האפליקציה.
‫PROJECT_NAMESPACE: מרחב השמות של הפרויקט.

לדוגמה, נקודת הקצה של Cortex לפרויקט project-1 בארגון org-1 היא https://console.org-1.zone1.google.gdch.test/project-1/cortex/metrics..

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

אימות הבקשה של `curl`

מורידים ומתקינים את ה-CLI של gdcloud.
מגדירים את המאפיין gdcloud core/organization_console_url:
```
gdcloud config set core/organization_console_url
https://GDC_URL
```
נכנסים לחשבון באמצעות ספק הזהויות שהוגדר:
```
gdcloud auth login
```
משתמשים בשם המשתמש ובסיסמה כדי לאמת את החשבון ולהיכנס אליו.

אחרי ההתחברות, אפשר להשתמש בכותרת ההרשאה בבקשת ה-curl באמצעות הפקודה gdcloud auth print-identity-token. מידע נוסף זמין במאמר gdcloud auth.

שליחת קריאה לנקודת הקצה של Cortex

כדי להגיע לנקודת הקצה של Cortex באמצעות הכלי curl:

מאמתים את הבקשה של curl.
משתמשים ב-curl כדי לשלוח קריאה לנקודת הקצה של Cortex ומרחיבים את כתובת ה-URL באמצעות פורמט השאילתות של HTTP API כדי לשלוח שאילתות לגבי מדדים.
בנוסף לפרמטרים של שאילתת כתובת URL של Prometheus, צריך לכלול פרמטר מיקום כדי לספק רשימה של אזורים לשאילתה. ‫- location={string}: רשימת אזורים שמופרדים באמצעות | - אם לא צוין, השאילתה תבוצע בכל האזורים הזמינים.

דוגמה לבקשת curl POST:
```
 curl POST \
 https://GDC_URL/PROJECT_NAME/cortex/metrics/api/v1/query_range" \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'query=pod_cpu_usage_total' \
--data-urlencode 'start=2025-07-21T16:00:00Z' \
--data-urlencode 'end=2025-07-21T16:15:00Z' \
--data-urlencode 'step=60s' \
--data-urlencode 'location=zone1|zone2' \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"
```
דוגמה לבקשת curl GET:
```
 curl -X GET \
 https://GDC_URL/PROJECT_NAME/cortex/metrics/api/v1/query_range?query=pod_cpu_usage_total&start=2025-07-21T16:00:00Z&end=2025-07-21T16:15:00Z&step=1s&location=zone1|zone2" \
-H "Authorization: Bearer $(gdcloud auth print-identity-token \
--audiences=https://GDC_URL)"
```
הפלט מתקבל אחרי הפקודה. התגובה מה-API היא בפורמט JSON.

הערה: צריך להוסיף את נקודת הקצה api/v1/query כדי לשלוח שאילתות לגבי מדדים מכתובת ה-URL. אפשר לכלול פרמטרים אופציונליים לקריאה ל-API אחרי סימן שאלה (?) בסוף כתובת ה-URL. מפרידים בין הפרמטרים האלה באמצעות סמלי אמפרסנד (&), כמו בדוגמה של הבקשה curl מהשלב הקודם.

שאילתות ותוויות לדוגמה

אפשר לשלוח שאילתות לגבי מדדים באמצעות שם המדד וצמדי מפתח/ערך של תוויות. התחביר של שאילתת PromQL הוא:

metric_name{label_one="value", label_two="value"}

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

לדוגמה, אפשר להשתמש במדד api_http_requests_total כדי לספור את מספר בקשות ה-HTTP שהתקבלו. אחר כך, אפשר להוסיף למדד הזה תווית request_method, שמקבלת ערך של POST,‏ GET או PUT. לכן, אתם יוצרים שלושה זרמי מדדים לכל סוג בקשה שאתם עשויים לקבל. במקרה כזה, כדי למצוא את מספר בקשות ה-HTTP מסוג GET, מריצים את השאילתה הבאה:

api_http_requests_total{request_method="GET"}

למידע נוסף על מדדים ותוויות, ראו מתן שמות למדדים ולתוויות.

אלה כמה מהתוויות שנוספות כברירת מחדל למשאב בהתאמה אישית MonitoringTarget. אתם יכולים להשתמש בתוויות ברירת המחדל האלה כדי לשלוח שאילתות לגבי מדדים:

‫_gdch_service: השם המקוצר של השירות.
‫cluster: שם האשכול.
‫container_name: שם הקונטיינר בתוך pod.
‫namespace_name: מרחב השמות של הפרויקט.
‫pod_name: התחילית של שם הפוד.

בטבלה הבאה מתוארות התוויות שנוספות באופן אוטומטי על ידי Prometheus:

תוויות ברירת מחדל
תווית המדד	תיאור
`job`	השם הפנימי של משימת הגירוד שמשמשת לאיסוף המדד. למשימות שנוצרו על ידי המשאב בהתאמה אישית `MonitoringTarget` יש שם בתבנית הבאה: `obs-system/OBS_SHADOW_PROJECT_NAME/MONITORINGTARGET_NAME.MONITORINGTARGET_NAMESPACE/I/J` `I` ו-`J` הם מספרים ייחודיים שנקבעים באופן פנימי כדי למנוע התנגשויות בין שמות.
`instance`	ה-`$IP:$PORT` של השירות שנסרק. אם למשאב של עומס עבודה יש כמה רפליקות, אפשר להשתמש בשדה הזה כדי להבדיל ביניהן.

דוגמת הקוד הבאה ממחישה את השימוש בצמדי מפתח/ערך של תוויות כדי לשלוח שאילתות לגבי מדדים שונים, במטרה להציג את השימוש ב-CPU שנאסף באשכול Kubernetes:

pod_cpu_usage_total{cluster="CLUSTER_NAME"}

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

הדוגמה הבאה היא של תשובה שהתקבלה מנקודת קצה של מדדי Cortex:

          {
    "zone1": {
      "status": "success",
      "data": {
        "resultType": "matrix",
        "result": [
          {
            "metric": {
              "__name__": "pod_cpu_usage_total",
              "_gdch_project": "project-1",
              "cluster": "root-admin",
              "container_name": "otel-collector",
              "exported_instance": "localhost:2112",
              "exported_job": "workload-0",
              "ha_cluster": "root-admin-shard1",
              "instance": "172.192.1.74:3113",
              "job": "metrics-server-exporter.mon-system",
              "namespace": "mon-system",
              "namespace_name": "mon-system",
              "pod": "cortex-0",
              "pod_name": "metrics-server-exporter-695c9f848b-swzgq",
              "zone_id": "zone1"
            },
            "values": [
              [
                1753261200,
                "2.258621991"
              ],
              [
                1753261800,
                "1.029301454"
              ]
            ]
          }
        ]
      }
    },
    "zone2": {
      "status": "success",
      "data": {
        "resultType": "matrix",
        "result": [
          {
            "metric": {
              "__name__": "pod_cpu_usage_total",
              "_gdch_project": "project-1",
              "cluster": "root-admin",
              "container_name": "otel-collector",
              "exported_instance": "localhost:2112",
              "exported_job": "workload-0",
              "ha_cluster": "root-admin-shard1",
              "instance": "172.196.3.208:3113",
              "job": "metrics-server-exporter.mon-system",
              "namespace": "mon-system",
              "namespace_name": "mon-system",
              "pod": "cortex-0",
              "pod_name": "metrics-server-exporter-695c9f848b-kchfv",
              "zone_id": "zone2"
            },
            "values": [
              [
                1753261200,
                "1.814027424"
              ],
              [
                1753261800,
                "2.7767060260000003"
              ]
            ]
          }
        ]
      }
    }
  }

שאילתות ל-HTTP API

סקירה כללית של הפורמט

התגובות מה-API מופיעות תמיד בפורמט JSON. בקשות שהושלמו בהצלחה תמיד יקבלו קוד סטטוס 2xx.

בבקשות לא חוקיות, ה-API handlers יחזירו אובייקט שגיאה בפורמט JSON יחד עם אחד מקודי הסטטוס הבאים של HTTP:

‫400 Bad Request: אם חסרים פרמטרים חיוניים או שהם לא נכונים.
‫503 Service Unavailable: אם השאילתות חורגות ממגבלת הזמן שלהן או שהן בוטלו.

כל הנתונים שנאספו בהצלחה ייכללו בשדה "data" של התגובה.

הפורמט של מעטפת התגובה ב-JSON הוא:

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only set if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"],
  // Only set if there were info-level annotations while executing the request.
  "infos": ["<string>"]
}

שאילתות מיידיות

נקודת הקצה (endpoint) הבאה מעריכה שאילתה מיידית בנקודת זמן אחת:

GET /api/v1/query
POST /api/v1/query

אפשר להשתמש בפרמטרים הבאים של שאילתות לגבי כתובות URL בשאילתות ביטויים של Prometheus:

‫query=<string>: מחרוזת השאילתה של הביטוי ב-Prometheus.
‫time=<rfc3339 | unix_timestamp>: חותמת זמן אופציונלית להערכה, שצוינה כמחרוזת RFC 3339 או כחותמת זמן של Unix. אם לא מציינים את הפרמטר, המערכת משתמשת בזמן הנוכחי בשרת.
‫timeout=<duration>: זמן קצוב אופציונלי להערכה. ערך ברירת המחדל הוא הערך של הדגל query.timeout, והוא מוגבל על ידיו.
‫limit=<number>: המספר המקסימלי האופציונלי של סדרות שיוחזרו. ההגדרה הזו מקצרת סדרות של מטריצות ווקטורים, אבל לא משפיעה על סקלרים או מחרוזות. הערך 0 משבית את המגבלה הזו.
‫lookback_delta=<number>: פרמטר אופציונלי לשינוי תקופת המבט לאחור במיוחד לשאילתה הזו.

אם משמיטים את פרמטר הזמן, המערכת משתמשת בזמן הנוכחי בשרת.

בשאילתות גדולות יותר שעשויות לחרוג ממגבלות התווים של כתובת ה-URL, אפשר לשלוח את הפרמטרים האלה באמצעות השיטה POST. מוודאים שגוף הבקשה מקודד בכתובת ה-URL ושהכותרת Content-Type מוגדרת ל-application/x-www-form-urlencoded.

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

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

‫<value> מתייחס לנתוני התוצאות של השאילתה, שיש להם פורמטים שונים בהתאם ל-resultType.

בדוגמה הבאה, הביטוי up מוערך בזמן 2015-07-01T20:10:51.781Z:

curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'

{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

שאילתות טווח

נקודת הקצה הבאה מעריכה שאילתת ביטוי בטווח זמן:

GET /api/v1/query_range
POST /api/v1/query_range

אפשר להשתמש בפרמטרים הבאים של שאילתות לגבי כתובות URL בשאילתות ביטויים של Prometheus:

‫query=<string>: מחרוזת השאילתה של הביטוי ב-Prometheus.
‫start=<rfc3339 | unix_timestamp>: חותמת הזמן של ההתחלה, כולל.
‫end=<rfc3339 | unix_timestamp>: חותמת זמן של סיום, כולל.
step=<duration | float>: רוחב שלב הרזולוציה של השאילתה בפורמט משך זמן או מספר שניות מסוג float.
‫timeout=<duration>: זמן קצוב אופציונלי להערכה. ערך ברירת המחדל הוא הערך של הדגל query.timeout, והוא מוגבל על ידיו.
‫limit=<number>: המספר המקסימלי האופציונלי של סדרות שיוחזרו. ההגדרה הזו מקצרת סדרות של מטריצות ווקטורים, אבל לא משפיעה על סקלרים או מחרוזות. הערך 0 משבית את המגבלה הזו.
‫lookback_delta=<number>: פרמטר אופציונלי לשינוי תקופת המבט לאחור במיוחד לשאילתה הזו.

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

{
  "resultType": "matrix",
  "result": <value>
}

בדוגמה הבאה, הביטוי up נבדק בטווח של 30 שניות עם רזולוציית שאילתה של 15 שניות.

curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'

{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

שמות של מדדים ותוויות

הנחיות למתן שמות למדדים

כשמגדירים שמות של מדדים, חשוב להביא בחשבון את העקרונות הבאים:

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

דוגמאות:
- ‫prometheus_notifications_total (ספציפי לשרת Prometheus)
- ‫process_cpu_seconds_total (מיוצא על ידי ספריות לקוח רבות)
- ‫http_request_duration_seconds (לכל בקשות ה-HTTP)
שם המדד חייב לייצג יחידה אחת (לדוגמה, אל תערבבו שניות עם אלפיות השנייה, או שניות עם בייטים).
שם המדד צריך להשתמש ביחידות בסיסיות (למשל, שניות, בייטים, מטרים) ולא ביחידות נגזרות (למשל, אלפיות השנייה, מגה-בייטים, קילומטרים).
שם המדד צריך לכלול סיומת של יחידה ברבים. בספירות מצטברות, צריך להשתמש בסיומת "total" בנוסף לסיומת היחידה, אם רלוונטי.

דוגמאות:
- http_request_duration_seconds
- node_memory_usage_bytes
- ‫http_requests_total (לספירה מצטברת ללא יחידות)
- ‫process_cpu_seconds_total (לספירה מצטברת עם יחידה)
- ‫foobar_build_info (למדד פסאודו שמספק מטא-נתונים על הקובץ הבינארי שפועל)
שם של מדד יכול לסדר את הרכיבים שלו כדי לאפשר קיבוץ נוח כשהוא ממוין באופן לקסיקוגרפי, בתנאי שכל שאר הכללים מתקיימים. למדדים קשורים יש לעיתים קרובות רכיבי שם משותפים שמופיעים בהתחלה כדי להבטיח שהם ימוינו יחד.

דוגמאות:
- prometheus_tsdb_head_truncations_closed_total
- prometheus_tsdb_head_truncations_established_total
- prometheus_tsdb_head_truncations_failed_total
- prometheus_tsdb_head_truncations_total
שם של מדד צריך לייצג באופן עקבי את אותו "דבר שנמדד" מבחינה לוגית בכל מאפייני התוויות.

דוגמאות:
- משך הבקשה
- בייטים של העברת נתונים
- שימוש מיידי במשאבים באחוזים

הנחיות למתן שמות לתוויות

כשמודדים משהו, משתמשים בתוויות כדי להבחין בין המאפיינים שלו. לדוגמה:

בבקשות HTTP כוללות ל-API (api_http_requests_total), צריך להבדיל לפי סוג הפעולה, לדוגמה create, ‏ update, ‏ delete (סוגי בקשות: operation="create|update|delete").
למשך בקשת ה-API בשניות (api_request_duration_seconds), מבדילים לפי שלב הבקשה, לדוגמה extract, ‏ transform, ‏ load (שלבי הבקשה: stage="extract|transform|load").

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

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

לפני שמתחילים

הגדרה 1

הגדרה 2

הגדרה 3

הגדרה 4

איך מקבלים ומסננים את המדדים

מרכזי בקרה של Grafana

זיהוי נקודת הקצה (endpoint) של Grafana

הצגת מדדים בממשק המשתמש של Grafana

נקודת קצה של Cortex – אזור אחד

זיהוי נקודת הקצה של Cortex

אימות הבקשה של curl

שליחת קריאה לנקודת הקצה של Cortex

נקודת קצה של Cortex – כמה אזורים

זיהוי נקודת הקצה של Cortex

אימות הבקשה של curl

שליחת קריאה לנקודת הקצה של Cortex

שאילתות ותוויות לדוגמה

שאילתות ל-HTTP API

סקירה כללית של הפורמט

שאילתות מיידיות

שאילתות טווח

שמות של מדדים ותוויות

הנחיות למתן שמות למדדים

הנחיות למתן שמות לתוויות

שאילתה והצגה של מדדים

אימות הבקשה של `curl`

אימות הבקשה של `curl`