v1.traces overview

במאמר הזה מוסבר למה מומלץ לשלוח את נתוני העקבות אל פרויקטGoogle Cloud באמצעות Telemetry (OTLP) API, שמטמיע את OpenTelemetry Protocol. הוא גם מספק הנחיות לגבי הטמעה של האפליקציות שלכם ומציין איפה אפשר לראות את נתוני המעקב. אפשר להשתמש ב-Telemetry API כשמשתמשים באחד מ-OpenTelemetry SDKs או ב-OpenTelemetry Collector כדי להוסיף לאפליקציות מכשור למעקב.

מומלץ להשתמש ב-Telemetry API מהסיבה הבאה:

  • ממשק ה-API תואם למערכת האקולוגית של OpenTelemetry בקוד פתוח, והמגבלות שלו לרוב נדיבות יותר מהמגבלות של Cloud Trace API, שהוא API קנייני של Google Cloud

  • נתוני העקבות מאוחסנים בפורמט שתואם בדרך כלל לקובצי הפרוטו שמוגדרים בפרוטוקול OpenTelemetry. יכול להיות שחלק מהשדות יומרו מסוג נתונים ספציפי ל-OpenTelemetry לסוג נתונים של JSON לפני האחסון. מידע נוסף על פורמט האחסון זמין במאמר בנושא סכימה של נתוני מעקב.

  • הטמעה לא מסתמכת על כלי ייצוא ספציפי ל- Google Cloud.

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

‫OpenTelemetry הוא פרויקט בקוד פתוח שנתמך על ידי Google CloudGoogle. מהנדסים של Google Google Cloudעובדים על הפרויקט כדי להבטיח תמיכה בהטמעה ובהמחשה חזותית של נתוני הטלמטריה שלכם.

‫Google Cloud Observability מוודא ש-Cloud Trace API מופעל בפרויקט Google Cloud לפני שהוא מאחסן נתוני מעקב. המשמעות היא שאם משביתים את Cloud Trace API, ‏ Google Cloud Observability משליך את נתוני העקבות ששולחים אל Telemetry API.

שיטות מומלצות

כשמגדירים את האפליקציות לשליחת נתוני מעקב אלGoogle Cloud הפרויקט, מומלץ להשתמש בכלי לייצוא שכותב נתונים בפורמט OTLP אל Collector, ששולח את נתוני המעקב אל Telemetry API. בכלי לאיסוף נתונים, מציינים רק את כתובת ה-URL הבסיסית:

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

‫OpenTelemetry מזהה את סוג הנתונים ומצרף באופן אוטומטי את /v1/traces,‏ /v1/metrics או /v1/logs לפי הצורך. מידע נוסף אפשר למצוא במאמר בנושא OTLP/HTTP Request.

דוגמאות לייצוא נתוני מעקב או מדדים ל-Telemetry API מופיעות במסמכים הבאים:

אם אתם לא יכולים להשתמש ב-Collector, אתם יכולים להשתמש בספריית OpenTelemetry שמכילה רכיב OTLP exporter בתוך התהליך כדי לשלוח נתוני טלמטריה אל Telemetry API. במאמר ייצוא נתוני מעקב לנקודת הקצה של OTLP מוסבר איך לייצא נתוני מעקב ישירות.

אימות

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

דוגמה לאימות כשמשתמשים בייצוא ישיר של נתוני מעקב מופיעה במאמר בנושא הגדרת אימות. בדוגמה הזו מוסבר איך להגדיר את כלי הייצוא באמצעות Google Cloud Application Default Credentials ‏ (ADC) ולהוסיף לאפליקציה ספריית אימות של Google שספציפית לשפה.

כדי לשלוח נתוני טלמטריה לפרויקט Google Cloud באמצעות Telemetry API, צריך גם:

  • הגדרה של פרויקט לצורכי מכסה. מידע נוסף זמין במאמר בנושא הגדרת פרויקט לצורכי מכסה.

  • מקצים למשתמש או לחשבון השירות שבו האפליקציה משתמשת את התפקידים הבאים בניהול הזהויות והרשאות הגישה (IAM):

    • התפקיד Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) בפרויקט של מכסת השימוש.
    • התפקיד Cloud Telemetry Writer‏ (roles/telemetry.writer) בפרויקט. התפקיד הזה מאפשר לאפליקציה לכתוב נתונים של יומנים, מדדים ומעקב.

‫Cloud Trace ומיקום אחסון הנתונים

אם אתם משתמשים ב-Assured Workloads כי יש לכם דרישות לגבי מיקום הנתונים או רמת ההשפעה 4 (IL4), אל תשתמשו ב-Telemetry API כדי לשלוח טווחים של מעקב לפרויקט שלכם.

איפה אפשר לראות את הנתונים שהועברו

אפשר לראות את נתוני העקבות בדפים Trace Explorer ו-Observability Analytics. מידע נוסף זמין במאמרים הבאים:

מכסות

מידע על מכסות שקשורות ל-Telemetry API זמין במאמר מגבלות של Telemetry API.