במסמך הזה מוסבר איך להשתמש ב-Observability API כדי לקבל מידע על קטגוריית ה-Observability שבה מאוחסנים נתוני המעקב. היא כוללת מידע על הוספה של מערכי נתונים, קישורים ותצוגות. מידע נוסף על אופן האחסון של נתוני העקבות זמין במאמר סקירה כללית על אחסון נתוני עקבות.
לפני שמתחילים
מגדירים את הפרויקט ואת תפקידי ה-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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Observability API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Observability API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
כדי לקבל את ההרשאות שנדרשות להצגת רשימה של קטגוריות, קישורים ותצוגות, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM Observability Viewer (
roles/observability.viewer) בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
בחירת הממשק שבו רוצים להשתמש
gcloud
במסוף Google Cloud , מפעילים את Cloud Shell.
בחלק התחתון של Google Cloud המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.
REST
כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של API בארכיטקטורת REST שבדף הזה, צריך להשתמש בפרטי הכניסה שאתם נותנים ל-CLI של gcloud.
התקינו את ה-CLI של Google Cloud.
אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-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
כדי לרשום את קטגוריות ה-Observability שנמצאות בפרויקט ובמיקום ספציפי, שולחים בקשה לנקודת הקצה 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.list עם הפרמטר parent שהוגדר לערך projects/my-project/locations/us, התגובה הייתה:
{
"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 זמינה במאמרי העזרה של Observability API.
הצגת רשימה של מערכי נתונים בקטגוריית נתונים של יכולת תצפית
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
השדות בביטוי הקודם מייצגים את המשמעויות הבאות:
- PROJECT_ID: מזהה הפרויקט.
- LOCATION: המיקום של קטגוריית ה-Observability.
- BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות
_Trace.
התגובה היא מערך של אובייקטים מסוג Dataset.
לכל אובייקט, הערך של השדה name הוא בפורמט הבא:
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/dataset/DATASET_ID
לדוגמה, כשפקודה הונפקה לנקודת הקצה buckets.datasets.list עם הפרמטר parent שהוגדר לערך projects/my-project/locations/us/buckets/_Trace, התגובה הייתה:
{
"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 זמינה במאמרי העזרה של Observability API.
הצגת רשימה של תצוגות במערך נתונים
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: המיקום של קטגוריית ה-Observability.
- BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות
_Trace. - DATASET_ID: המזהה של מערך הנתונים שנשלחת אליו השאילתה. לדוגמה, המזהה יכול להיות
Spans.
התגובה היא מערך של אובייקטים מסוג View.
לכל אובייקט, הערך של השדה name הוא בפורמט הבא:
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/views/OBS_VIEW_ID
בדוגמה הקודמת, המזהה של תצוגה מיוצג על ידי OBS_VIEW_ID.
לדוגמה, הערך בשדה הזה יכול להיות _AllSpans.
לדוגמה, כשפקודה הונפקה לנקודת הקצה buckets.datasets.views.list עם הפרמטר parent שהוגדר לערך projects/my-project/locations/us/buckets/_Trace/datasets/Spans/views, התגובה הייתה:
{
"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 זמינה במאמרי העזרה של Observability API.
הצגת רשימת קישורים במערך נתונים
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: המיקום של קטגוריית ה-Observability.
- BUCKET_ID: המזהה של קטגוריית הנתונים של יכולת התצפית. לדוגמה, המזהה יכול להיות
_Trace. - DATASET_ID: המזהה של מערך הנתונים שנשלחת אליו השאילתה. לדוגמה, המזהה יכול להיות
Spans.
התגובה היא מערך של אובייקטים Link.
לכל אובייקט, הערך של השדה name הוא בפורמט הבא:
projects/PROJECT_ID/locations/LOCATION/buckets/BUCKET_ID/links/LINK_ID
LINK_ID הוא השם של מערך הנתונים ב-BigQuery. השדה הזה ייחודי באופן גלובלי עבור Google Cloud הפרויקט.
לדוגמה, כשפקודה הונפקה לנקודת הקצה buckets.datasets.links.list עם הפרמטר parent שהוגדר לערך projects/my-project/locations/us/buckets/_Trace/datasets/Spans/links, התגובה הייתה:
{
"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 זמינה במאמרי העזרה של Observability API.
יצירת קישור לקבוצת נתונים
בקטע הזה מוסבר איך ליצור קישור למערך נתונים, כדי שתוכלו להריץ שאילתות על נתוני המעקב מ-BigQuery.
פעולות מערכת שמתרחשות כשיוצרים מערך נתונים מקושר
כשיוצרים מערך נתונים מקושר, מתחיל תהליך ארוך טווח. כמה פעולות מתבצעות כחלק מהפעולה הזו:
- ביומני הביקורת מתועדת הבקשה ליצירת קישור והשלמת הפעולה.
אם חשבון השירות של Monitoring לא קיים, הוא נוצר על ידי Google Cloud Observability.
כדי ליצור את חשבון השירות הזה, צריך להפעיל את Cloud Monitoring API.
כדי ליצור מערך נתונים מקושר, צריך להגדיר חשבון שירות ב-Google Cloud Observability. כשצריך, נוצר חשבון שירות:
חשבון שירות של Cloud Observability: נדרש לקישור במערך נתונים של ניראות.
חשבון שירות של Cloud Logging: נדרש לקישור בקטגוריית יומנים.
יומן הביקורת מתעד את הבקשה של מנהל סוכני השירות להעניק לחשבון השירות של Monitoring את תפקיד ה-IAM Monitoring Service Agent.
לפני שמתחילים
- משלימים את ההגדרה הנדרשת כדי להציג קישורים.
-
מפעילים את Cloud Monitoring API.
תפקידים שנדרשים להפעלת ממשקי API
כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (
roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאהserviceusage.services.enable. איך מקצים תפקידים -
כדי לקבל את ההרשאות שדרושות ליצירת קישור במערך נתונים, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- עורך יכולת הצפייה (
roles/observability.editor) - BigQuery User (
roles/bigquery.user)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
- עורך יכולת הצפייה (
יצירת מערך נתונים מקושר ב-BigQuery
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: המיקום של קטגוריית ה-Observability.
- 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/dataset/DATASET_ID/links/LINK_IDהערך שאתם מציינים בשדה
nameצריך להיות זהה למערך הנתונים המקושר ב-BigQuery שאליו מתייחס פרמטר השאילתה.השדה LINK_ID הוא השם של מערך הנתונים ב-BigQuery.
התגובה היא אובייקט Operation.
האובייקט הזה מכיל מידע על ההתקדמות של השיטה. כששיטת הגיבוי מסתיימת, אובייקט Operation מכיל נתוני סטטוס.
רשימה מלאה של נקודות הקצה של Observability API זמינה במאמרי העזרה של Observability API.
אם נתקלתם בשגיאות הרשאה כשניסיתם ליצור מערך נתונים מקושר, כדאי לעיין במאמר בנושא פתרון בעיות שקשורות להרשאות.
המאמרים הבאים
מידע נוסף על השימוש בדף Trace Explorer זמין במאמר חיפוש עקבות וניתוח שלהם.
במאמר הגדרת ברירות מחדל לקטגוריות של נתונים שניתנים לצפייה מוסבר איך מגדירים מיקום אחסון שמוגדר כברירת מחדל ואיך מגדירים מפתחות הצפנה בניהול הלקוח (CMEK) לקטגוריות של נתונים שניתנים לצפייה.