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

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

אחרי איסוף המדדים מעומסי העבודה שפרסתם ב-Google Distributed Cloud ‏ (GDC) עם בידוד פיזי, תוכלו להתחיל לנתח אותם. כדי לנתח מדדים, אפשר להציג אותם בתצוגה חזותית ולסנן אותם במרכזי בקרה אינפורמטיביים של 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	org-admin	`project-grafana-viewer`	platform-obs	קבוצה	1
PA	cortex	org-admin	`project-cortex-prometheus-viewer`	platform-obs	קבוצה	2
PA	grafana	org-admin	`project-grafana-viewer`	platform-obs	משתמש	3
PA	cortex	org-admin	`project-cortex-prometheus-viewer`	platform-obs	משתמש	4
AO	grafana	org-admin	`project-grafana-viewer`	PROJECT_NAMESPACE	קבוצה	1
AO	cortex	org-admin	`project-cortex-prometheus-viewer`	PROJECT_NAMESPACE	קבוצה	2
AO	grafana	org-admin	`project-grafana-viewer`	PROJECT_NAMESPACE	משתמש	3
AO	cortex	org-admin	`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 endpoint במסמך הזה כדי לשלוח שאילתות למדדים באופן פרוגרמטי.

פקודת 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 endpoint במסמך הזה כדי לשלוח שאילתות למדדים באופן פרוגרמטי.

פקודת 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.

זיהוי נקודת הקצה של 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.
לוחצים על הצגת הכול ב-Grafana.

ייפתח דף חדש עם נקודת הקצה של Grafana ויוצג ממשק המשתמש.
בממשק המשתמש, לוחצים על ניתוח ניתוח בתפריט הניווט כדי לפתוח את הדף ניתוח.
בתפריט בסרגל ניתוח, בוחרים מקור נתונים כדי לאחזר מדדים, בהתאם לסוג היקום:
- יקומים עם אזור אחד: בוחרים באפשרות prometheus כדי להציג מדדים מהאזור היחיד של היקום.
- יקומים רב-אזוריים: אפשר לחבר את Grafana לאזורים שונים ולהציג נתונים חוצי-אזורים. בוחרים באפשרות מדדים ZONE_NAME כדי להציג מדדים מכל אזור ביקום, בלי קשר לאזור שאליו נכנסתם.
  
  בנוסף, כדי ליצור תרשימים של נתונים מאזורים שונים בלוח בקרה אחד ולהוסיף כמה אזורים לשאילתה, בוחרים באפשרות מעורב כמקור הנתונים.
מזינים שאילתה כדי לחפש מדדים באמצעות ביטויים של PromQL (שפת שאילתות של Prometheus). אפשר לבצע את השלב הזה באחת מהדרכים הבאות:
- בתפריטים מדד ומסנני תוויות בוחרים מדד ותווית לשאילתה. לוחצים על הוספה הוספה כדי להוסיף עוד תוויות לשאילתה. אחר כך לוחצים על Run query.
- מזינים את השאילתה ישירות בשדה הטקסט מדדים ומקישים על 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`

הורדה והתקנה של gdcloud CLI
מגדירים את מאפיין core/organization_console_url של gcloud:
```
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`

הורדה והתקנה של gdcloud CLI
מגדירים את מאפיין core/organization_console_url של gcloud:
```
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 custom resource. אפשר להשתמש בתוויות ברירת המחדל האלה כדי לשלוח שאילתות לגבי מדדים:

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

בטבלה הבאה מתוארות התוויות ש-Prometheus מוסיף באופן אוטומטי:

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

בדוגמת הקוד הבאה מוצג שימוש בצמדי מפתח/ערך לתוויות כדי לשלוח שאילתה למדדים שונים ולראות את השימוש במעבד שנאסף באשכול 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 יחזירו אובייקט שגיאה בפורמט JSON יחד עם אחד מקודי הסטטוס הבאים של HTTP:

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

כל הנתונים שנאספו בהצלחה ייכללו בשדה '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>"]
}

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

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

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.

בדוגמה הבאה מוערך הביטוי עד לזמן 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>: רוחב שלב הפתרון של השאילתה בפורמט משך או מספר עשרוני של שניות.
‫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

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

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

נקודת קצה של Cortex – תחום יחיד

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

אימות הבקשה curl

התקשרות לנקודת הקצה של Cortex

נקודת קצה של Cortex – רב-אזורי

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

אימות הבקשה curl

התקשרות לנקודת הקצה של Cortex

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

שאילתות HTTP API

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

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

שאילתות לגבי טווח

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

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

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

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

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

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