יצירת קטגוריות של נתונים לצורך יכולת צפייה

כדי להתאים אישית את מיקום האחסון ואת ההגדרות של מפתח הצפנה בניהול הלקוח (CMEK), אתם יכולים ליצור באופן ידני את קטגוריית הניראות _Trace לפני שהפרויקט מקבל נתוני מעקב. אם הפרויקט ב- Google Cloud מקבל נתוני מעקב לפני שהקטגוריה הזו קיימת, Google Cloud Observability מקצה באופן אוטומטי את הקטגוריה באמצעות הגדרות ברירת המחדל של הפרויקט לקטגוריות של ניטור.

במאמר סקירה כללית על אחסון מוסבר איך Google Cloud Observability מאחסן נתונים.

אינטראקציה עם כללי מדיניות של הארגון

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

אינטראקציה עם הגדרות ברירת המחדל של קטגוריות ניתנות-לצפייה

כש-Google Cloud Observability יוצרת באופן אוטומטי קטגוריית תצפית בגלל הטמעת נתונים, היא משתמשת בהגדרות ברירת המחדל של קטגוריות התצפית שחלות על משאב ההורה של הקטגוריה. הגדרות ברירת המחדל האלה יכולות להיות מוגדרות בהורה או באב קדמון היררכי של ההורה, והן מציינות את הפרטים הבאים:

  • מיקום האחסון.
  • המפתח של Cloud KMS שבו משתמשים לנתונים שמאוחסנים.

כשיוצרים קטגוריית תצפית, צריך לציין מיקום. ב-Google Cloud Observability, המערכת משתמשת במפתח Cloud KMS שמוגדר כברירת מחדל, אלא אם מציינים מפתח אחר בבקשת היצירה.

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

במאמר הגדרת ברירות מחדל לקטגוריות של ניראות מוסבר איך להגדיר את ברירות המחדל של קטגוריות הניראות.

מגבלות

ההגבלות הבאות חלות:

  • צריך לציין מיקום נתמך.
  • הערך של BUCKET_ID חייב להיות _Trace.
  • השם המוצג לא יכול להיות ארוך מ-100 בייטים מקודדים.
  • התיאור יכול להכיל עד 1,000 בייטים מקודדים.
  • הנתונים נשמרים במשך 30 ימים. צריך להשמיט את תקופת השמירה או להגדיר אותה בתור 30.
  • אם אתם מספקים מפתח Cloud KMS, המיקום של המפתח חייב להתאים בדיוק למיקום ההורה של קטגוריית הניטור.
  • אפשר ליצור קטגוריות של ניראות רק בפרויקטים ב- Google Cloud .
  • לפרויקט ב- Google Cloud יכולה להיות לכל היותר קטגוריית תצפית אחת בשם _Trace.

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

מגדירים את הפרויקט ואת תפקידי ה-IAM, ובוחרים את הממשק שבו רוצים להשתמש.

הגדרת הפרויקט והתפקידים

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the Observability API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. כדי לקבל את ההרשאות שנדרשות ליצירת קטגוריות של ניראות, צריך לבקש מהאדמין להקצות לכם את התפקיד עריכת ניראות (roles/observability.editor) ב-IAM בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

הגדרת ממשקים

gcloud

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

gcloud init

Terraform

כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של Terraform שבדף הזה, מתקינים ומפעילים את ה-CLI של gcloud, ואז מגדירים את Application Default Credentials באמצעות פרטי הכניסה של המשתמש.

  1. התקינו את ה-CLI של Google Cloud.

  2. הגדירו שה-CLI של gcloud ישתמש בזהות המאוחדת שלכם.

    איך נכנסים ל-CLI של gcloud באמצעות הזהות המאוחדת?

  3. צרו פרטי כניסה לאימות מקומי בחשבון המשתמש: 

    gcloud auth application-default login

    אם מופיעה שגיאת אימות, ודאו ש נכנסתם ל-CLI של gcloud באמצעות הזהות המאוחדת שלכם.

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

REST

כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של API בארכיטקטורת REST שבדף הזה, צריך להשתמש בפרטי הכניסה שאתם נותנים ל-CLI של gcloud.

    התקינו את ה-CLI של Google Cloud ואז היכנסו ל-CLI של gcloud באמצעות הזהות המאוחדת שלכם.

מידע נוסף מופיע במאמר אימות לשימוש ב-REST במסמכי האימות של Google Cloud .

הגדרת מפתח Cloud KMS

זה שינוי אופציונלי. אם אתם מתכננים ליצור קטגוריית תצפית ולציין מפתח Cloud KMS, בצעו את הפעולות הבאות:

  1. מפעילים את Cloud Key Management Service API, אם הוא עדיין לא מופעל.

    התפקידים שנדרשים כדי להפעיל ממשקי API

    כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

    להפעלת ה-API

  2. יוצרים אוסף מפתחות ומפתחות.

    המיקום של קטגוריית הניטור חייב להיות זהה למיקום של המפתח.

  3. מחליפים את PROJECT_ID במזהה הפרויקט ומריצים את הפקודה הבאה:

    gcloud observability settings describe \
--location=global --project=PROJECT_ID

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

  4. מקצים לחשבון השירות של Google Cloud Observability את התפקיד Cloud KMS CryptoKey Encrypter/Decrypter.

    gcloud kms keys add-iam-policy-binding \
--project=KMS_PROJECT_ID \
--member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-observability. \
--role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
--location=KMS_KEY_LOCATION \
--keyring=KMS_KEY_RING \
KMS_KEY_NAME

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

    • ‫KMS_PROJECT_ID: המזהה האלפאנומרי הייחודי של הפרויקט ב- Google Cloud שבו פועל Cloud KMS, שמורכב משם הפרויקט ב- Google Cloud וממספר שהוקצה באופן אקראי. איך מזהים פרויקטים?
    • ‫service-PROJECT_NUMBER: השם של חשבון השירות של Observability שמופיע בתשובה של השלב הקודם.
    • ‫KMS_KEY_LOCATION: האזור של המפתח ב-Cloud KMS.
    • ‫KMS_KEY_RING: השם של אוסף המפתחות ב-Cloud KMS.
    • ‫KMS_KEY_NAME: השם של המפתח ב-Cloud KMS. הפורמט שלו הוא: projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KMS_KEY_RING/cryptoKeys/KEY.

יצירת קטגוריית תצפיתיות

gcloud

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

  • ‫BUCKET_ID: המזהה של קטגוריית הניטור. לדוגמה, המזהה יכול להיות _Trace.
  • ‫LOCATION: המיקום של קטגוריית הניטור.
  • ‫PROJECT_ID: מזהה הפרויקט.

הפקודה של ה-CLI של gcloud מספקת גם אפשרויות להגדרת השם המוצג, התיאור והמפתח של Cloud KMS. מידע נוסף זמין במאמר gcloud observability buckets create.

מריצים את הפקודה gcloud observability buckets create:

‫Linux,‏ macOS או Cloud Shell

gcloud observability buckets create BUCKET_ID \
 --location=LOCATION --project=PROJECT_ID

‏Windows (PowerShell)

gcloud observability buckets create BUCKET_ID `
 --location=LOCATION --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud observability buckets create BUCKET_ID ^
 --location=LOCATION --project=PROJECT_ID

הפקודה create מפעילה פעולה ממושכת וחוסמת עד שהפעולה מסתיימת. זו דוגמה לתגובה כשהפקודה מסתיימת ללא שגיאות: 

Create request issued for: [_Trace]
Waiting for operation [projects/my-project/locations/us/operations/operation-1775164903749-64e80c9817833-9ff804b6-c3e9cbe7] to complete...done.
Created bucket [_Trace].

Terraform

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

  • ‫project: מזהה הפרויקט.
  • ‫location: המיקום של קטגוריית הניטור. מידע נוסף זמין במאמר מיקומים.
  • ‫bucket_id: המזהה של קטגוריית הניטור. צריך להגדיר את השדה הזה לערך _Trace.

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

REST

כדי ליצור קטגוריית ניראות (observability), שולחים בקשה לכתובת projects.locations.buckets.create.

צריך לציין את הפרמטר הראשי, שמופיע בפורמט הבא:

projects/PROJECT_ID/locations/LOCATION

המשמעות של השדות בביטוי שלמעלה:

גוף הבקשה הוא אובייקט Bucket. ממלאים את השדות הבאים:

  • ‫name: מגדירים את השדה הזה כך:

    projects/PROJECT_ID/locations/LOCATION/buckets/_Trace

  • אופציונלי: מזינים ערכים בשדות displayName ו-description.

  • אופציונלי: מספקים מפתח CMEK. כשמציינים את המפתח הזה, הוא מצפין את הנתונים שמאוחסנים.

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

התגובה היא אובייקט Operation. דוגמים את השיטה projects.locations.operations.get עד שהשדה Operation.done מוגדר ל-true. שדות אחרים במבנה Operation מספקים מידע על הצלחת הבקשה או על כישלונה.

הצגת רשימה של קטגוריות של ניראות

אתם יכולים להציג את רשימת הקטגוריות של נתוני הניטור כדי לוודא שבקשת היצירה הושלמה בהצלחה.

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

gcloud

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

  • ‫LOCATION: המיקום של הקטגוריות של נתוני התצפית. כדי להציג את כל קטגוריות ה-Observability, בלי קשר למיקום, מגדירים את המיקום כמקף (-).
  • ‫PROJECT_ID: מזהה הפרויקט.

מריצים את הפקודה gcloud observability buckets list:

‫Linux,‏ macOS או Cloud Shell

gcloud observability buckets list \
 --location=LOCATION --project=PROJECT_ID

‏Windows (PowerShell)

gcloud observability buckets list `
 --location=LOCATION --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud observability buckets list ^
 --location=LOCATION --project=PROJECT_ID

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

---
createTime: '2026-01-21T21:39:22.381083860Z'
description: Bucket for storing spans from Cloud Trace.
name: projects/my-project/locations/us/buckets/_Trace

Terraform

אי אפשר להשתמש ב-Terraform כדי להציג רשימה של קטגוריות תצפית.

REST

כדי להציג את רשימת הקטגוריות של נתוני התצפיתיות בפרויקט ובמיקום ספציפי, משתמשים ב-method‏ projects.locations.buckets.list.

צריך לציין את הפרמטר הראשי, שמופיע בפורמט הבא:

projects/PROJECT_ID/locations/LOCATION

המשמעות של השדות בביטוי הקודם:

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: המיקום של קטגוריית הניראות. אם מגדירים את LOCATION למקף (-), כל הקטגוריות של ניראות המערכת בפרויקט מופיעות ברשימה.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

זוהי דוגמה לתשובה:

{
  "buckets": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace",
      "description": "Trace Bucket",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
      "retentionDays": 30
    }
  ]
}

אתם יכולים להשתמש ב-Observability API כדי לקבל מידע נוסף על הקטגוריה שהמזהה שלה הוא BUCKET_ID. לדוגמה, אתם יכולים להציג את רשימת מערכי הנתונים בקטגוריה הזו, ואת התצוגות והקישורים בכל מערך נתונים. מידע נוסף מופיע במאמרי העזרה של Observability API.

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