עבודה עם ה-API

במסמך הזה מוסבר איך לנהל שירותים ויעדים ברמת השירות (SLO) באמצעות Cloud Monitoring API.

השירות Service Monitoring מוסיף את המשאבים הבאים ל-Monitoring API:

במסמך הזה, התוספות האלה נקראות ביחד SLO API, ומוצגים בו השימושים העיקריים שלהן. סקירה כללית של המבנים ב-SLO API מופיעה במאמר Constructs in the API. חומר עזר מקיף מופיע בקטע Cloud Monitoring API v3.

אפשר להשתמש ב-SLO API כדי:

ליצור ולנהל שירותים.
יצירת יעדים למדידת רמת השירות (SLO) על סמך אינדיקטורים מותאמים אישית או מוגדרים מראש למדידת רמת השירות (SLI) לכל אחד מהשירותים.

מזהים תקינים

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

אורך: 1-63 תווים
תווים: רק אותיות קטנות, מספרים ומקפים
התו הראשון: אות קטנה
התו האחרון: אות קטנה או מספר, אבל לא מקף

הביטוי הרגולרי של הכללים האלה הוא: [a-z](?:[-a-z0-9]{0,61}[a-z0-9])?

דוגמאות לשימוש ב-`curl`

בקטע הזה מוסבר על המוסכמות וההגדרות שמשמשות להפעלת SLO API באמצעות הכלי curl. אם אתם משתמשים ב-API הזה דרך ספריית לקוח, אתם יכולים לדלג על הקטע הזה.

בדוגמאות שבדף הזה נעשה שימוש בכלי curl כדי לשלוח בקשות HTTP לנקודות קצה של REST, וכך לגשת ל-API של SLO. כדי להגדיר את המשתנים שמשמשים להפעלות, צריך להשתמש במידע הבא על אימות ועל הפעלה של curl.

אימות

יוצרים משתנה סביבה שיכיל את המזהה של פרויקט ההיקף של היקף מדדים: בדוגמאות האלה נעשה שימוש ב-PROJECT_ID:
```
PROJECT_ID=my-test-service
```
מאמתים את הזהות ב-Google Cloud CLI:
```
gcloud auth login
```
כדי שלא תצטרכו לציין את מזהה הפרויקט בכל פקודה, אתם יכולים להגדיר אותו כברירת מחדל באמצעות ה-CLI של gcloud:
```
gcloud config set project ${PROJECT_ID}
```
יוצרים אסימון הרשאה ושומרים אותו במשתנה סביבה. בדוגמאות האלה מופעל המשתנה ACCESS_TOKEN:
```
ACCESS_TOKEN=`gcloud auth print-access-token`
```
צריך לרענן את אסימון הגישה מדי פעם. אם פקודות שפעלו פתאום מדווחות שאין לכם אימות, צריך להנפיק מחדש את הפקודה הזו.
כדי לוודא שקיבלתם אסימון גישה, מריצים את הפקודה הבאה:ACCESS_TOKEN
```
echo ${ACCESS_TOKEN}
ya29.GluiBj8o....
```

ביצוע הפעולה `curl`

כל הפעלה של curl כוללת קבוצה של ארגומנטים, ואחריה כתובת ה-URL של משאב SLO API. הארגומנטים הנפוצים כוללים ערכים שצוינו על ידי משתני הסביבה PROJECT_ID ו-ACCESS_TOKEN. יכול להיות שתצטרכו לציין גם ארגומנטים אחרים, למשל כדי לציין את סוג בקשת ה-HTTP (לדוגמה, -X DELETE). בקשת ברירת המחדל היא GET, ולכן לא מצוין סוג הבקשה בדוגמאות.

לכל הפעלה של curl יש את המבנה הכללי הזה:

curl --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

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

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services

הבקשה הזו מחזירה מערך של תיאורי שירות, עם רשומות כמו הבאה, שירות של עומס עבודה ב-GKE עם מזהה השירות my-test-service:

{
  "services": [
    {
      "name": "projects/PROJECT_NUMBER/services/my-test-service",
      "displayName": "My Test GKE Workload Service",
      "basicService": {
        "serviceType": "GKE_WORKLOAD",
        "serviceLabels": {
          "cluster_name": "workload-test",
          "location": "us-central1-c",
          "namespace_name": "kube-system",
          "project_id": "lesser-weevil",
          "top_level_controller_name": "gke-metrics-controller",
          "top_level_controller_type": "DaemonSet"
        }
      },
      "gkeWorkload": {
        "projectId": "lesser-weevil",
        "location": "us-central1-c",
        "clusterName": "workload-test",
        "namespaceName": "kube-system",
        "topLevelControllerType": "DaemonSet",
        "topLevelControllerName": "gke-metrics-controller"
      },
      "source": "USER",
      "telemetry": {
        "resourceName": "//container.googleapis.com/projects/PROJECT_ID/zones/us-central1-c/clusters/workload-test/k8s/namespaces/kube-system/apps/daemonsets/gke-metrics-controller"
      }
    },
   ...
  ]
}

כדי לראות את ההגדרה ששימשה ליצירת השירות הזה, אפשר לעיין במאמר יצירת שירות. שימו לב שהמבנה של gkeWorkload ברשימה הזו נגזר מהמבנה של basicService ששימש ליצירת השירות. מידע נוסף על המבנה של שירות זמין במאמר Service.

ניהול שירותים

המשאב Service משמש כרכיב הבסיסי לארגון השירותים. היבטים של שירות מסוים, כמו יעדי ה-SLO שלו, מאורגנים תחת שם השירות. אלה סוגי השירותים שנתמכים:

שירות App Engine: APP_ENGINE
שירות Cloud Endpoints: CLOUD_ENDPOINTS
שירות Istio רשמי (קנוני): ISTIO_CANONICAL_SERVICE
שירות Istio באשכול: CLUSTER_ISTIO
שירות Cloud Run: CLOUD_RUN
קבוצה של שירותים שמבוססים על Google Kubernetes Engine:‏
- שירות GKE: GKE_SERVICE
- מרחב שמות של GKE: GKE_NAMESPACE
- עומס עבודה (workload) של GKE: GKE_WORKLOAD
שירותים בהתאמה אישית: CUSTOM

מידע נוסף זמין במאמרים סוגי שירותים בסיסיים או סוגי שירותים בסיסיים של GKE.

אפשר להוסיף יעדי SLO לכל שירות בפרויקט באמצעות ה-API. במאמר ניהול יעדי זמינות (SLO) מוסבר על פקודות לשינוי יעדי זמינות.

מזהי שירות

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

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-a-cloudrun-istio-system-cluster-local-gateway",

שם המשאב כולל מזהה קצר יותר של השירות, שהוא החלק של שם המשאב אחרי המחרוזת המשנה projects/PROJECT_NUMBER/services/

אם יצרתם שירות משלכם עם שם המשאב projects/PROJECT_NUMBER/services/my-test-service, מזהה השירות הוא my-test-service.

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

פרסום שירותים

כדי לאחזר מידע על כל השירותים בפרויקט, מפעילים את השיטה services.list. כדי לאחזר מידע על שירות ספציפי לפי מזהה השירות, משתמשים בשיטה services.get:

פרוטוקול

כדי להציג רשימה של מידע על שירותים באמצעות curl, צריך להפעיל את השיטה services.list או services.get על ידי שליחת בקשת GET אל:

‫https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services כדי לראות רשימה של כל השירותים
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID כדי לקבל שירות ספציפי

לדוגמה, הבקשה הבאה מאחזרת מידע על השירות שמזוהה על ידי הערך שמאוחסן במשתנה הסביבה SERVICE_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

יצירת שירות

כדי ליצור שירות, מציינים ייצוג של סוג השירות ושולחים אותו לשיטה services.create. אפשר להשתמש במבני סוגי השירותים שמתוארים במאמרים סוגי שירותים בסיסיים וסוגי שירותים בסיסיים של GKE.

המבנים שונים, אבל התהליך של קריאה ל-API זהה. צריך לציין שם לתצוגה של השירות ושדה basicService שמכיל את הייצוג של השירות.

אפשר גם לציין את מזהה השירות שרוצים להקצות לשירות. בדוגמה הבאה מוצגת יצירה של שירות עומס עבודה של {[gke_name_short}}:

פרוטוקול

כדי ליצור את השירות באמצעות curl, שולחים הודעה מסוג POST לנקודת הקצה https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services:

אם רוצים לספק מזהה לשירות, יוצרים משתנה למזהה השירות:
```
SERVICE_ID=my-test-service
```
הערך הזה מועבר בפרמטר השאילתה בכתובת ה-URL‏ service_id.

יוצרים משתנה שיכיל את גוף הבקשה שמתאר את השירות:

CREATE_SERVICE_POST_BODY=$(cat <<EOF
{
  "displayName": "My Test GKE Workload Service",
  "basicService": {
    "serviceType": "GKE_WORKLOAD",
    "serviceLabels": {
      "cluster_name": "workload-test",
      "location": "us-central1-c",
      "namespace_name": "kube-system",
      "project_id": "PROJECT_ID",
      "top_level_controller_name": "gke-metrics-controller",
      "top_level_controller_type": "DaemonSet"
    }
  }
}
EOF
)

שולחים את גוף הבקשה לנקודת הקצה ומציינים את מזהה השירות כערך של פרמטר השאילתה service_id:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SERVICE_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services?service_id=${SERVICE_ID}

דוגמאות למבנים שמשויכים לשירותים אחרים מופיעות במאמרים סוגי שירותים בסיסיים או סוגי שירותים בסיסיים של GKE.

מחיקת שירות

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

פרוטוקול

כדי למחוק שירות באמצעות curl, שולחים בקשת DELETE לנקודת הקצה https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}

ניהול יעדי זמינות (SLO)

אתם יכולים ליצור, למחוק ולאחזר יעדי SLO באמצעות SLO API. אפשר להגדיר עד 500 יעדי SLO לכל שירות.

כדי לנהל את יעדי ה-SLO של שירות, צריך את מזהה השירות. השם של SLO מבוסס על השירות שאליו הוא שייך. מידע על זיהוי מזהי שירות זמין במאמר מזהי שירות.

יעדים למדידת רמת השירות (SLO) של כרטיסי מוצר

כדי לאחזר מידע על כל יעדי ה-SLO שמשויכים לשירות, מפעילים את השיטה services.serviceLevelObjectives.list. כדי לאחזר מידע על SLO ספציפי לפי שם, משתמשים במתודה services.serviceLevelObjectives.get:

פרוטוקול

כדי להציג רשימה של מידע על שירותים באמצעות curl, צריך להפעיל את השיטה services.serviceLevelObjectives.list או services.serviceLevelObjectives.get על ידי שליחת בקשת GET אל:

‫https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives כדי לראות את כל יעדי ה-SLO
https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/[SERVICE_ID]/serviceLevelObjectives/SLO_ID כדי לקבל SLO ספציפי

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

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

הנה SLO של זמינות שאוחזר מהשירות currencyservice:

{
  "name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",
  "displayName": "98% Availability in Calendar Week"
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.98,
  "calendarPeriod": "WEEK",
},

היעד למדידת רמת השירות הזה מבוסס על מדד אמינות (SLI) של זמינות, הוא מגדיר יעד ביצועים של 98% ומודד את התאימות במהלך שבוע קלנדרי. מידע נוסף על SLI של זמינות זמין במאמר בנושא אינדיקטורים לרמת השירות.

מידע נוסף על המבנה של יעדי זמינות (SLO) זמין במאמר ServiceLevelObjective.

אחזור של יעד SLO ספציפי

לכל יעד SLO יש מזהה ייחודי בתוך השירות, שמורכב מהמחרוזת שאחרי serviceLevelObjectives בשדה name של יעד ה-SLO. בדוגמה הבאה:

"name": "projects/PROJECT_NUMBER/services/PROJECT_ID-zone-us-central1-c-csm-main-default-currencyservice/serviceLevelObjectives/3kavNVTtTMuzL7KcXAxqCQ",

מזהה ה-SLO הוא המחרוזת 3kavNVTtTMuzL7KcXAxqCQ.

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

פרוטוקול

כדי לקבל SLO ספציפי באמצעות curl, מפעילים את method‏ services.serviceLevelObjectives.get על ידי שליחת בקשת GET אל https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID:

SLO_ID=dhefHDM4TwSRZEKIV4ZYEg

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

יצירת SLO

כדי ליצור SLO באמצעות SLO API, צריך ליצור אובייקט ServiceLevelObjective ולהעביר אותו ל-method‏ serviceLevelObjectives.create.

המבנה של SLO מכיל הרבה מבנים מוטמעים, כולל מבנה אחד לערך של השדה serviceLevelIndicator.

ב-Cloud Service Mesh, ב-Istio ב-Google Kubernetes Engine ובשירותי App Engine, מדדי ה-SLI מוגדרים מראש. אפשר להשתמש במסוף Cloud Service Mesh כדי ליצור יעדי זמינות. כל מה שצריך לעשות הוא לציין את יעדי הביצועים ואת תקופות התאימות.
בשירותים אחרים, צריך להגדיר את ה-SLO באמצעות SLO API. כדי לציין יעד SLO, צריך ליצור ערך גם בשדה serviceLevelIndicator. במאמר יצירת אינדיקטורים ברמת השירות מפורטות כמה טכניקות, ובמאמר יצירת אינדיקטורים ברמת השירות מתוך מדדים מופיעות דוגמאות שמבוססות על מקורות שונים.

אפשר ליצור SLI גם באמצעות מסוף Google Cloud . מידע נוסף זמין במאמר יצירת SLO.

שלד של SLO

השלד הבסיסי לבניית SLO הוא כדלקמן:

{
  "displayName": string,
  "serviceLevelIndicator": {
    object (ServiceLevelIndicator)
  },
  "goal": number,

  // Union field period can be only one of the following:
  "rollingPeriod": string,
  "calendarPeriod": enum (CalendarPeriod)
  // End of list of possible types for union field period.
}

צריך לציין את הפרטים הבאים:

השם המוצג: תיאור של יעד ה-SLO
מדד רמת שירות (SLI), שהוא אחד משלושת הסוגים הבאים:
יעד הביצועים (באחוזים)
תקופת התאימות, שיכולה להיות אחת משני הסוגים הבאים:
- תקופה מתמשכת באורך מסוים (בשניות)
- תקופה ביומן

מידע נוסף על SLI, יעדי ביצועים ותקופות תאימות זמין במאמר מושגים בניטור שירותים.

ב-Cloud Service Mesh, ב-Istio ב-Google Kubernetes Engine ובשירותי App Engine, סוג ה-SLI הוא SLI בסיסי.

בשביל שירותים אחרים, צריך ליצור SLI מבוסס-בקשות או SLI מבוסס-חלונות. במאמר יצירת מדד רמת שירות מוסברות כמה טכניקות.

דוגמה

אחרי שיש לכם את ה-SLI, תוכלו ליצור את ה-SLO. בדוגמה הבאה מוגדר SLO לשירות שמשתמש ב-SLI בסיסי. יכול להיות שיש לכם כמה יעדי רמת שירות (SLO) במדד אמינות שירות (SLI) אחד. לדוגמה, אחד לזמינות של 95% ואחד לזמינות של 99%. הדוגמה הבאה היא SLO לזמינות של 95% במהלך שבוע קלנדרי:

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.95,
  "calendarPeriod": "WEEK",
  "displayName": "95% Availability in Calendar Week"
}

בדוגמה הזו מציינים יעד SLO של 75% זמינות במהלך תקופה מתגלגלת של 3 ימים:

{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}

פרוטוקול

כדי ליצור SLO באמצעות curl, שולחים הודעת POST לנקודת הקצה https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives:

יוצרים משתנה למזהה השירות:
```
SERVICE_ID=custom:my-test-service
```

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

CREATE_SLO_POST_BODY=$(cat <<EOF
{
  "serviceLevelIndicator": {
    "basicSli": {
      "availability": {},
      "location": [
        "us-central1-c"
      ]
    }
  },
  "goal": 0.75,
  "rollingPeriod": "259200s",
  "displayName": "75% Availability in Rolling 3 Days"
}
EOF
)

שולחים את גוף הבקשה לנקודת הקצה:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives

אפשר גם לציין מזהה רצוי ל-SLO כערך של פרמטר השאילתה service_level_objective_id:

SLO_ID=test-slo-id

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" --header "Content-Type: application/json" -X POST -d "${CREATE_SLO_POST_BODY}" https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives?service_level_objective_id=${SLO_ID}

מחיקת SLO

כדי למחוק SLO, מפעילים את השיטה services.serviceLevelObjectives.delete ומציינים את מזהה ה-SLO בפרויקט:

פרוטוקול

כדי למחוק יעד SLO באמצעות curl, שולחים בקשת DELETE לנקודת הקצה https://monitoring.googleapis.com/v3/projects/[PROJECT_ID]/services/SERVICE_ID/serviceLevelObjectives/SLO_ID:

curl  --http1.1 --header "Authorization: Bearer ${ACCESS_TOKEN}" -X DELETE https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/services/${SERVICE_ID}/serviceLevelObjectives/${SLO_ID}

גישה לפעולות על ציר הזמן של SLO

נתוני SLO מאוחסנים כסדרות זמן, כך שאפשר להשתמש בשיטה timeSeries.list כדי לאחזר אותם. עם זאת, הנתונים האלה לא מאוחסנים בסוגי מדדים רגילים, ולכן אי אפשר להשתמש במנגנון הרגיל של ציון מסנן לפי סוג מדד בשיטה timeSeries.list.

במקום זאת, כדי לאחזר סדרות זמן של SLO, צריך לציין סוג אחר של מסנן, בורר סדרות זמן, בשיטה timeSeries.list בפרמטר filter. מידע על השימוש בסלקטורים האלה זמין במאמר אחזור נתוני SLO.

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

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

מזהים תקינים

דוגמאות לשימוש ב-curl

אימות

ביצוע הפעולה curl

ניהול שירותים

מזהי שירות

פרסום שירותים

פרוטוקול

יצירת שירות

פרוטוקול

מחיקת שירות

פרוטוקול

ניהול יעדי זמינות (SLO)

יעדים למדידת רמת השירות (SLO) של כרטיסי מוצר

פרוטוקול

אחזור של יעד SLO ספציפי

פרוטוקול

יצירת SLO

שלד של SLO

דוגמה

פרוטוקול

מחיקת SLO

פרוטוקול

גישה לפעולות על ציר הזמן של SLO

עבודה עם ה-API

דוגמאות לשימוש ב-`curl`

ביצוע הפעולה `curl`