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

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

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

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

מגדירים את הפרויקט ואת התפקידים בניהול הזהויות והרשאות הגישה (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.

    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. כדי לקבל את ההרשאות שנדרשות להצגת רשימה של קטגוריות, קישורים ותצוגות, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM‏ Observability Viewer (roles/observability.viewer) בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

בחירת הממשק שבו רוצים להשתמש

gcloud

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

gcloud init

REST

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

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

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

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

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

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

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

‏Windows (PowerShell)

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

Windows‏ (cmd.exe)

gcloud beta 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

REST

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

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

projects/PROJECT_ID/locations/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.

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

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

gcloud

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

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

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

‫Linux,‏ macOS או Cloud Shell

gcloud beta observability buckets datasets list \
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

‏Windows (PowerShell)

gcloud beta observability buckets datasets list `
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud beta observability buckets datasets list ^
 --bucket=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

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

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

REST

כדי להציג רשימה של מערכי הנתונים של מאגר נתונים לצורך ניטור, משתמשים בשיטה projects.locations.buckets.datasets.list.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID

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

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

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

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

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

הצגת רשימה של תצוגות במערך נתונים

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

gcloud

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

  • ‫DATASET_ID: מזהה קבוצת הנתונים. נתוני המעקב מאוחסנים במערך נתונים בשם Spans.
  • ‫BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות _Trace.
  • ‫LOCATION: המיקום של קטגוריות הנתונים של יכולת התצפית.
  • ‫PROJECT_ID: מזהה הפרויקט.

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

‫Linux,‏ macOS או Cloud Shell

gcloud beta observability buckets datasets views list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID \
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

‏Windows (PowerShell)

gcloud beta observability buckets datasets views list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID `
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud beta observability buckets datasets views list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID ^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

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

---
createTime: '2026-01-21T21:39:22.381083860Z'
displayName: _AllSpans
name: projects/pamstestproject1/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans
updateTime: '2026-01-21T21:39:22.381083860Z'

REST

כדי להציג את התצוגות במערך נתונים, משתמשים בשיטה projects.locations.buckets.datasets.views.list.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views

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

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: המיקום של קטגוריית הנתונים של יכולת התצפית.
  • ‫BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות _Trace.
  • ‫DATASET_ID: המזהה של מערך הנתונים שנשלחת אליו השאילתה. לדוגמה, המזהה יכול להיות Spans.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/views/OBS_VIEW_ID

בביטוי שלמעלה, המזהה של תצוגה מיוצג על ידי OBS_VIEW_ID. לדוגמה, הערך בשדה הזה יכול להיות _AllSpans.

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

{
  "views": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views/_AllSpans",
      "filter": "",
      "createTime": "2025-01-01T15:42:30.988919645Z",
      "updateTime": "2025-02-04T15:42:30.988919645Z",
    }
  ]
}

מידע נוסף מופיע במאמרי העזרה של Observability API.

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

gcloud

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

  • ‫DATASET_ID: מזהה קבוצת הנתונים. נתוני המעקב מאוחסנים במערך נתונים בשם Spans.
  • ‫BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות _Trace.
  • ‫LOCATION: המיקום של קטגוריות הנתונים של יכולת התצפית.
  • ‫PROJECT_ID: מזהה הפרויקט.

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

‫Linux,‏ macOS או Cloud Shell

gcloud beta observability buckets datasets links list \
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

‏Windows (PowerShell)

gcloud beta observability buckets datasets links list `
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud beta observability buckets datasets links list ^
 --dataset=projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

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

---
createTime: '2026-04-02T21:23:09.272323714Z'
name: projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/mydataset

REST

כדי להציג את הקישורים במערך נתונים, משתמשים בשיטה projects.locations.buckets.datasets.links.list.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

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

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: המיקום של קטגוריית הנתונים של יכולת התצפית.
  • ‫BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות _Trace.
  • ‫DATASET_ID: המזהה של מערך הנתונים שנשלחת אליו השאילתה. לדוגמה, המזהה יכול להיות Spans.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID

‫LINK_ID הוא השם של מערך הנתונים ב-BigQuery. השדה הזה ייחודי ברמה הגלובלית לפרויקט Google Cloud שלכם.

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

{
  "links": [
    {
      "name": "projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links/my_link",
      "description": "My link for traces to BigQuery",
      "createTime": "2025-01-12T15:42:30.988919645Z"
    }
  ]
}

מידע נוסף מופיע במאמרי העזרה של Observability API.

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

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

  • יכול להיות ש-Google Cloud Observability ייצור את חשבונות השירות הבאים או ישנה את ההרשאות שלהם בתפקידי IAM:

  • ביומני הביקורת מתועדת הבקשה ליצירת קישור והבקשה מאדמין של סוכן שירות להעניק לחשבון השירות של Monitoring את תפקיד ה-IAM‏ Monitoring Service Agent. ביומנים האלה מתועד גם השלמת הפעולה הממושכת.

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

  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 Cloud Monitoring and Observability APIs.

    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 APIs

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

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

gcloud

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

  • ‫LINK_ID: השם של מערך הנתונים ב-BigQuery.
  • ‫DATASET_ID: מזהה קבוצת הנתונים. נתוני המעקב מאוחסנים במערך נתונים בשם Spans.
  • ‫BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות _Trace.
  • ‫LOCATION: המיקום של קטגוריות הנתונים של יכולת התצפית.
  • ‫PROJECT_ID: מזהה הפרויקט.

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

‫Linux,‏ macOS או Cloud Shell

gcloud beta observability buckets datasets links create \
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID \
 --dataset=DATASET_ID\
 --bucket=BUCKET_ID \
 --location=LOCATION \
 --project=PROJECT_ID

‏Windows (PowerShell)

gcloud beta observability buckets datasets links create `
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID `
 --dataset=DATASET_ID`
 --bucket=BUCKET_ID `
 --location=LOCATION `
 --project=PROJECT_ID

Windows‏ (cmd.exe)

gcloud beta observability buckets datasets links create ^
  projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID ^
 --dataset=DATASET_ID^
 --bucket=BUCKET_ID ^
 --location=LOCATION ^
 --project=PROJECT_ID

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

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

REST

כדי ליצור קישור למערך נתונים ב-BigQuery, שולחים בקשה לנקודת הקצה projects.locations.buckets.datasets.links.create.

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

projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID

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

  • ‫PROJECT_ID: מזהה הפרויקט.
  • ‫LOCATION: המיקום של קטגוריית הנתונים של יכולת התצפית.
  • ‫BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות _Trace.
  • ‫DATASET_ID: המזהה של מערך הנתונים שנשלחת אליו השאילתה. לדוגמה, המזהה יכול להיות Spans.

הפקודה הזו דורשת פרמטר של שאילתה וגוף בקשה:

  • צריך לציין את פרמטר השאילתה, linkId, ולהגדיר אותו לשם של מערך הנתונים ב-BigQuery. לדוגמה, linkId="my_link". שם קבוצת הנתונים ב-BigQuery חייב להיות ייחודי לפרויקט Google Cloud , והוא יכול לכלול רק אותיות, ספרות וקווים תחתונים. השם מוגבל ל-100 תווים.

  • גוף הבקשה הוא אובייקט Link. הערך בשדה name הוא בפורמט הבא:

    projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/datasets/DATASET_ID/links/LINK_ID

    הערך שאתם מציינים בשדה name צריך להיות זהה למערך הנתונים המקושר ב-BigQuery שאליו מתייחס פרמטר השאילתה.

    השדה LINK_ID הוא השם של מערך הנתונים ב-BigQuery.

התגובה היא אובייקט Operation. האובייקט הזה מכיל מידע על ההתקדמות של השיטה. כששיטת הגיבוי מסתיימת, אובייקט Operation מכיל נתוני סטטוס.

רשימה מלאה של נקודות הקצה של Observability API זמינה במאמרי העזרה של Observability API.

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

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