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

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

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

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

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

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

כשמערכת Google Cloud Observability יוצרת באופן אוטומטי קטגוריה של נתונים לצורך ניתוח נתונים (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, ובוחרים את הממשק שמתכננים להשתמש בו.

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

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

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

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

הגדרת ממשקים

gcloud

הערה: אתם צריכים להשתמש ב-CLI של gcloud בגרסה 586.0.0 ואילך.

במסוף Google Cloud , מפעילים את Cloud Shell.

הפעלת Cloud Shell

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

Terraform

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

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

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

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

   gcloud auth application-default login

   אם אתם משתמשים ב-Cloud Shell, אתם לא צריכים לעשות את זה.

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

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

REST

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

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

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

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

הגדרת מפתח Cloud KMS

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

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

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

   כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (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:[e-mail] \
   --role=roles/cloudkms.cryptoKeyEncrypterDecrypter \
   --location=KMS_KEY_LOCATION \
   --keyring=KMS_KEY_RING \
   KMS_KEY_NAME
   

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

   • ‫KMS_PROJECT_ID: המזהה האלפאנומרי הייחודי, שמורכב מ Google Cloud שם הפרויקט וממספר שהוקצה באופן אקראי, של הפרויקט Google Cloud שמריץ את Cloud KMS. במאמר זיהוי פרויקטים מוסבר איך מקבלים את המזהה הזה.
   • ‫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

הערה: אתם צריכים להשתמש ב-CLI של gcloud בגרסה 586.0.0 ואילך.

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

• ‫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 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

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

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

projects/PROJECT_ID/locations/LOCATION

השדות בביטוי שלמעלה מייצגים את הדברים הבאים:

• ‫PROJECT_ID: מזהה הפרויקט.
• ‫LOCATION: המיקום של קטגוריית ה-Observability.

גוף הבקשה הוא אובייקט 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

הערה: אתם צריכים להשתמש ב-CLI של gcloud בגרסה 586.0.0 ואילך.

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

• ‫LOCATION: המיקום של קטגוריות הנתונים של יכולת התצפית. כדי להציג רשימה של כל קטגוריות הנתונים של יכולת הצפייה, בלי קשר למיקום, צריך להגדיר את המיקום למקף (-).
• ‫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

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

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

projects/PROJECT_ID/locations/LOCATION

השדות בביטוי הקודם מייצגים את הדברים הבאים:

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

התגובה היא מערך של אובייקטים מסוג 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.

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

• חיפוש ועריכה של עקבות

• שאילתה וניתוח של עקבות באמצעות SQL

• הגדרת ברירות מחדל לקטגוריות של נתונים לצורך ניטור: הגדרת מיקום אחסון שמוגדר כברירת מחדל ומפתח הצפנה בניהול הלקוח (CMEK) שמוגדר כברירת מחדל לקטגוריות של נתונים לצורך ניטור.