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

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

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

היקפי המדדים ומרכז האפליקציות

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

הפעלת השיטה הזו יוצרת רשומה ביומני הביקורת של הפרויקט שמוגדר כפרויקט היקף. לא מתבצעת קריאה לשיטת ה-API הזו במסוף Google Cloud . לכן, שינויים שמתבצעים בהיקף של מדדים כשמשתמשים ב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.

הפעלת השיטה הזו יוצרת רשומה ביומני הביקורת של הפרויקט שמוגדר כפרויקט היקף. לא מתבצעת קריאה לשיטת ה-API הזו במסוף Google Cloud . לכן, שינויים שמתבצעים בהיקף של מדדים כשמשתמשים ב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'

כדי לזהות את הפרויקט לפי המזהה שלו, מריצים את הפקודה gcloud projects list ומסננים לפי מזהה הפרויקט. Google Cloud לדוגמה, כדי לקבל את השם של הפרויקט 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.

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

    SCOPING_PROJECT_ID_OR_NUMBER=SCOPING_PROJECT_ID_OR_NUMBER

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

    MONITORED_PROJECT_ID_OR_NUMBER=MONITORED_PROJECT_ID_OR_NUMBER

  3. מאמתים את ה-CLI של Google Cloud:

    gcloud auth login

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

    gcloud config set project ${SCOPING_PROJECT_ID_OR_NUMBER}

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

    TOKEN=`gcloud auth print-access-token`

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

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

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

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

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

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