הגדרת היקף מדדים באמצעות API

במאמר הזה מוסבר איך להשתמש ב-Google Cloud CLI או ב-Cloud Monitoring API כדי להגדיר את היקף המדדים של פרויקט Google Cloud . הדף הזה מיועד למפתחים ולאדמינים של מערכות.

אפשר גם להשתמש ב-Terraform כדי להגדיר היקף מדדים. מידע נוסף זמין במאמר Terraform registry for google_monitoring_monitored_project.

היקפי המדדים והאפליקציות של App Hub

אתם מנהלים את היקף המדדים של פרויקטים מארחים ופרויקטים לניהול ב-App Hub עבור גבולות של פרויקט יחיד. אפשר לנהל את היקף המדדים באמצעות מסוףGoogle Cloud או Cloud Monitoring API.

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

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

  • אם אתם לא מכירים את המונחים היקף המדדים והיקף הפרויקט, כדאי לעיין במאמר היקפי מדדים.

  • צריך לוודא שתפקידי ניהול הזהויות והרשאות הגישה (IAM) שלכם בפרויקט ההיקף ובכל פרויקט שאתם רוצים להוסיף להיקף המדדים או להסיר ממנו, כוללים את כל ההרשאות בתפקיד אדמין של Monitoring‏ (roles/monitoring.admin). מידע נוסף זמין במאמר בנושא הגדרות של היקף מדדים.

  • השיטות של Cloud Monitoring API שמאחזרות מידע הן סינכרוניות, אבל ממשקי ה-API שמשנים את המצב הם אסינכרוניים. פקודות Google Cloud CLI נחסמות עד שהפעולה האסינכרונית מסתיימת. מידע על בדיקת השלמה של שיטה אסינכרונית של API ועל בדיקת הסטטוס שלה זמין במאמר שיטות אסינכרוניות של API.

  • אם אתם מתכננים להפעיל את Cloud Monitoring API באמצעות curl או אם אתם רוצים להשתמש בדוגמאות שבדף הזה, אתם צריכים להשלים את השלבים של הגדרת הפקודה curl.

הוספת פרויקט להיקף המדדים

gcloud

כדי להוסיף פרויקט להיקף של מדדים, מריצים את הפקודה gcloud beta monitoring metrics-scopes create: Google Cloud 

gcloud beta monitoring metrics-scopes create MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER

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

  • מזינים את השם או המזהה של Google Cloud הפרויקט שהיקף המדדים שלו ישונה למשתנה SCOPING_PROJECT_ID_OR_NUMBER. בהגדרות של מרכז האפליקציות, בוחרים את פרויקט המארח או את פרויקט הניהול של מרכז האפליקציות.

  • מזינים את המזהה של הפרויקט שבמעקב למשתנה MONITORED_PROJECT_ID_OR_NUMBER. הפורמט הוא projects/PROJECT_ID_OR_NUMBER.

לדוגמה, הפקודה הבאה מוסיפה את הפרויקט my-monitored-project להיקף המדדים של הפרויקט שנקרא my-staging-projects:

gcloud beta monitoring metrics-scopes create projects/my-monitored-project --project=my-staging-projects

התגובה לפקודה הקודמת מאשרת שהפקודה הושלמה בהצלחה:

Created monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

curl

כדי להוסיף Google Cloud פרויקט להיקף של מדדים, שולחים בקשת POST לנקודת הקצה locations.global.metricsScopes.projects.create:

curl -H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" -X POST \
-d "{'name': 'locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}'}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects

בדוגמה הקודמת, משתני הסביבה מוגדרים כך:

  • ‫MONITORED_PROJECT_ID_OR_NUMBER מאחסן את מזהה הפרויקט שיוסף להיקף המדדים.
  • ‫SCOPING_PROJECT_ID_OR_NUMBER מאחסן את מזהה הפרויקט שמתעדכן בו היקף המדדים.

התגובה של השיטה האסינכרונית הזו היא אובייקט Operation.

אפליקציות שקוראות לשיטה הזו צריכות לדגום את נקודת הקצה operation.get עד שהערך בשדה Operation.done הוא true. כשהערך של השדה Operation.done מוגדר בתור false, המשמעות היא שהפעולה נמצאת בתהליך. מידע נוסף מופיע במאמר בנושא פקודות API אסינכרוניות.

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

{
  "name": "operations/6915efde-1915-400a-ad49-7b62041d9bd2",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.MonitoredProject",
    "name": "locations/global/metricsScopes/012012012012/projects/678678678678",
    "provider": "G​C​P",
    "providerAccountId": "...",
    ...
  }
}

בתשובה הקודמת, השדה Operation.done מוגדר לערך true. הערך הזה מציין שהפקודה הושלמה. מכיוון שהפקודה הושלמה בהצלחה, השדה Operation.response מוגדר והערך שלו הוא אובייקט MonitoredProject. השדה response.name כולל את המזהה של הפרויקט שמוגדר כפרויקט היקף ואת הפרויקט שבמעקב. בשדה providerAccountId מופיע שם הפרויקט שבמעקב.

הפעלת ה-method הזו יוצרת רשומה ביומני הביקורת של פרויקט ההיקף. המסוף Google Cloud לא מפעיל את שיטת ה-API הזו. לכן, שינויים שבוצעו בהיקף של מדדים כשמשתמשים במסוףGoogle Cloud לא מתועדים ביומני הביקורת.

הסרת פרויקט מהיקף המדדים

gcloud

כדי להסיר Google Cloud פרויקט מהיקף המדדים, מריצים את הפקודה gcloud beta monitoring metrics-scopes delete:

gcloud beta monitoring metrics-scopes delete MONITORED_PROJECT_ID_OR_NUMBER --project=SCOPING_PROJECT_ID_OR_NUMBER

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

  • מזינים את השם או המזהה של Google Cloud הפרויקט שהיקף המדדים שלו ישונה למשתנה SCOPING_PROJECT_ID_OR_NUMBER. בהגדרות של מרכז האפליקציות, בוחרים את פרויקט המארח או את פרויקט הניהול של מרכז האפליקציות.

  • מזינים את המזהה של הפרויקט שבמעקב למשתנה MONITORED_PROJECT_ID_OR_NUMBER. הפורמט הוא projects/PROJECT_ID_OR_NUMBER.

לדוגמה, הפקודה הבאה מסירה את הפרויקט my-monitored-project מהיקף המדדים של הפרויקט בשם my-staging-projects:

gcloud beta monitoring metrics-scopes delete projects/my-monitored-project --project=my-staging-projects

התגובה לפקודה הקודמת מאשרת שהפקודה הושלמה בהצלחה:

Deleted monitored project [locations/global/metricsScopes/my-staging-projects/projects/my-monitored-project].

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

NOT_FOUND: Requested entity was not found.

curl

כדי להסיר Google Cloud פרויקט מהיקף המדדים, שולחים בקשת DELETE לנקודת הקצה locations.global.metricsScopes.projects.delete:

curl -H "Authorization: Bearer ${TOKEN}" -X DELETE \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}/projects/${MONITORED_PROJECT_ID_OR_NUMBER}

בדוגמה הקודמת, משתני הסביבה מוגדרים כך:

  • ‫MONITORED_PROJECT_ID_OR_NUMBER מאחסן את מזהה הפרויקט שיוסר מהיקף המדדים.
  • ‫SCOPING_PROJECT_ID_OR_NUMBER מאחסן את מזהה הפרויקט שמתעדכן בו היקף המדדים.

התגובה לשיטה האסינכרונית הזו היא אובייקט Operation.

אפליקציות שקוראות לשיטה הזו צריכות לדגום את נקודת הקצה operation.get עד שהערך בשדה Operation.done הוא true. כשהערך של השדה Operation.done מוגדר בתור false, המשמעות היא שהפעולה נמצאת בתהליך. מידע נוסף מופיע במאמר בנושא פקודות API אסינכרוניות.

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

{
  "name": "operations/4367ff34-0ff0-4767-b8d3-0638e30f077c",
  "metadata": {
    "@type": "type.googleapis.com/google.monitoring.metricsscope.v1.OperationMetadata",
    "state": "DONE",
    ...
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

בתשובה הקודמת, השדה Operation.done מוגדר לערך true. הערך הזה מציין שהפקודה הושלמה. הפקודה הושלמה בהצלחה, ולכן השדה Operation.response מוגדר ומכיל את השדה @type.

הפעלת ה-method הזו יוצרת רשומה ביומני הביקורת של פרויקט ההיקף. המסוף Google Cloud לא מפעיל את שיטת ה-API הזו. לכן, שינויים שבוצעו בהיקף של מדדים כשמשתמשים במסוףGoogle Cloud לא מתועדים ביומני הביקורת.

הצגת רשימה של כל היקפי המדדים שכוללים פרויקט

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

gcloud

כדי לקבל רשימה של היקפי מדדים שיכולים להציג את המדדים של פרויקטGoogle Cloud , מריצים את הפקודה gcloud beta monitoring metrics-scopes list:

gcloud beta monitoring metrics-scopes list MONITORED_PROJECT_ID_OR_NUMBER

לפני שמריצים את הפקודה, מזינים את המזהה של הפרויקט שבמעקב במשתנה MONITORED_PROJECT_ID_OR_NUMBER. הפורמט הוא projects/PROJECT_ID_OR_NUMBER..

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

gcloud beta monitoring metrics-scopes list projects/my-project

התגובה הבאה מציינת שהפרויקט my-project נכלל בשני היקפי מדידה:

metricsScopes:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345
  updateTime: '2018-08-18T16:20:37.032928Z'
- createTime: '2021-04-13T15:37:26.869Z'
  name: locations/global/metricsScopes/9876543210
  updateTime: '2021-04-13T15:37:27.284239Z'

כדי לקבל מידע מפורט על היקף מדדים, מריצים את הפקודה gcloud beta monitoring metrics-scopes describe.

curl

כדי לקבל רשימה של היקפי מדדים שיכולים להציג את המדדים של פרויקט, שולחים בקשת GET לנקודת הקצה locations.global.metricsScopes.listMetricsScopesByMonitoredProject וכוללים את פרמטר השאילתה שמציין את הפרויקט.

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes:listMetricsScopesByMonitoredProject?monitored_resource_container=projects/${PROJECT_ID_OR_NUMBER}

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

אם הפעולה בוצעה ללא שגיאות, התשובה היא מערך של אובייקטים מסוג MetricsScope.

ה-method הזו לא גורמת לכתיבת רשומה ביומני הביקורת של פרויקט ההיקף. כדי שהפעולות האלה יתועדו ביומן הביקורת, צריך להפעיל את האפשרות Data Read עבור Cloud Resource Manager API. מידע נוסף זמין במאמר הגדרת יומני ביקורת של גישה לנתונים.

קבלת פרטים על היקף מדדים

בקטע הזה מוסבר איך למצוא פרטים על היקף ספציפי של מדדים.

gcloud

כדי לקבל מידע מפורט על היקף המדדים, מריצים את הפקודה gcloud beta monitoring metrics-scopes describe:

gcloud beta monitoring metrics-scopes describe METRICS_SCOPE_ID

לפני שמריצים את הפקודה, מזינים את השם של תחום המדדים המלא במשתנה METRICS_SCOPE_ID. להלן דוגמה לשם מוגדר במלואו:

locations/global/metricsScopes/012345012345

זוהי דוגמה לתגובה. בדוגמה הזו, היקף המדדים מכיל פרויקט אחד, והמזהה של היקף המדדים ושל הפרויקט זהה:

createTime: '2018-08-06T17:13:42Z'
monitoredProjects:
- createTime: '2018-08-06T17:13:42Z'
  name: locations/global/metricsScopes/012345012345/projects/012345012345
name: locations/global/metricsScopes/012345012345
updateTime: '2018-08-18T16:20:37.032928Z'

כדי לזהות את Google Cloud הפרויקט לפי המזהה שלו, מריצים את הפקודה gcloud projects list ומסננים לפי מזהה הפרויקט. לדוגמה, כדי לקבל את השם של הפרויקט 012345012345, מריצים את הפקודה הבאה:

gcloud projects list --filter="012345012345" --format="value(NAME)"

curl

כדי לקבל מידע על היקף מדדים, שולחים בקשת GET לנקודת הקצה locations.global.metricsScopes.get:

curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/${SCOPING_PROJECT_ID_OR_NUMBER}

בדוגמה הקודמת, משתנה הסביבה SCOPING_PROJECT_ID_OR_NUMBER מאחסן את מזהה הפרויקט של היקף המדדים שנשלחת לגביו שאילתה.

אם הפעולה בוצעה ללא שגיאות, התגובה היא אובייקט MetricsScope.

ה-method הזו לא גורמת לכתיבת רשומה ביומני הביקורת של פרויקט ההיקף. כדי שהפעולות האלה יתועדו ביומן הביקורת, צריך להפעיל את האפשרות Data Read עבור Cloud Resource Manager API. מידע נוסף זמין במאמר הגדרת יומני ביקורת של גישה לנתונים.

שיטות API אסינכרוניות

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

אפליקציות שקוראות לשיטת API אסינכרונית צריכות לדגום את נקודת הקצה operation.get עד שהערך בשדה Operation.done הוא true:

  • כשהערך של done הוא false, הפעולה מתבצעת.

    כדי לרענן את פרטי הסטטוס, שולחים בקשת GET לנקודת הקצה operation.get:

    curl -H "Authorization: Bearer ${TOKEN}" \
https://monitoring.googleapis.com/v1/${OPERATION_NAME}

    בפקודה הקודמת, OPERATION_NAME הוא משתנה סביבה שמאחסן את הערך של השדה Operation.name.

  • כשהערך של done הוא true, הפעולה הושלמה ואחד מהשדות error או response מוגדר:

    • ‫error: אם הערך מוגדר, הפעולה האסינכרונית נכשלה. הערך של השדה הזה הוא אובייקט Status שמכיל קוד שגיאה של gRPC והודעת שגיאה.
    • ‫response: כשהערך מוגדר, הפעולה האסינכרונית הושלמה בהצלחה, והערך משקף את התוצאה.

הגדרת פקודות curl

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

curl -H "Authorization: Bearer ${TOKEN}" <other_args> \
https://monitoring.googleapis.com/v1/locations/global/metricsScopes/<resource>

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

  1. יוצרים את משתנה הסביבה כדי לאחסן את מזהה או מספר פרויקט ההיקף. אם אתם משתמשים ב-App Hub, צריך להגדיר את המשתנה הזה למזהה של פרויקט המארח ב-App Hub או למזהה של פרויקט הניהול של התיקייה לניהול אפליקציות:

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

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

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

  3. מאמתים את הזהות ב-Google Cloud CLI:

    gcloud auth login

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

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

  5. יוצרים אסימון הרשאה ושומרים אותו במשתנה סביבה:

    TOKEN=`gcloud auth print-access-token`

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

  6. כדי לוודא שקיבלתם אסימון גישה, מריצים את הפקודה הבאה:TOKEN

    echo ${TOKEN}
ya29.GluiBj8o....

יכול להיות שתצטרכו לציין גם ארגומנטים אחרים, למשל כדי לציין את סוג בקשת ה-HTTP (לדוגמה, -X DELETE). בקשת ברירת המחדל היא GET, ולכן בדוגמאות לא מצוין סוג הבקשה.

המאמרים הבאים

למידע על שימוש ב- Google Cloud עם Terraform, אפשר לעיין במשאבים הבאים: