Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

עבודה עם ה-API

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

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

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

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

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

מזהים תקינים

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

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

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

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

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

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

אימות

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

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

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

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

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 שמשויכים למזהה השירות שמאוחסן במשתנה הסביבה 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",
},

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

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

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

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

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

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

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

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