סקירה כללית על v1.logs

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

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

המבנה הכללי של נתוני יומן בפורמט OTLP

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

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "logRecords": [...]
        }
      ]
    }
]

שימו לב ש-OpenTelemetry מאגדת קבוצות של יומנים נפרדים, שכל אחד מהם מיוצג על ידי מבנה logRecord, עם מידע על המקור של היומנים האלה, שמיוצג על ידי מבנה resource.

כש-Google Cloud Observability מקבל אובייקט resourceLogs, הוא יוצר LogEntry אחד לכל logRecord. בניגוד ל-OTLP שבו מידע המקור נאסף באצווה עם אוסף של יומנים נפרדים, כל מבנה LogEntry מכיל מידע על המקור של היומן ועל היומן עצמו.

מידע נוסף על המבנה של נתוני יומן בפורמט OTLP זמין בlogs.proto של OpenTelemetry.

איך מעבדים נתוני יומן בפורמט OTLP

כששולחים מבנה OTLP resourceLogs אל Telemetry API,‏ Google Cloud Observability מבצע את הפעולות הבאות:

  1. לכל logRecord, המערכת יוצרת LogEntry.

    במסמכים הבאים מוסבר איך המערכת מאכלסת את LogEntry מנתוני היומן של OTLP:

    מכיוון שכל LogEntry מכיל מידע על סוג המשאב התואם ב-Cloud Logging, יכול להיות שכל LogEntry יהיה גדול יותר מ-logRecord OTLP התואם.

    יכול להיות שההמרה ממבנה OTLP resourceLogs לסדרה של מבנים LogEntry תגרום לאובדן נתונים. כלומר, יכול להיות שלא תוכלו להמיר מהמבנה LogEntry לשדות המקוריים resource ו-logRecord.

  2. השדה LogEntry מנותב על ידי מאגרי מידע מצטברים בהיררכיית הפרויקט ועל ידי מאגרי מידע בפרויקט, בדיוק כמו אם רשומת היומן נשלחה לפרויקט באמצעות Cloud Logging 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 שספציפית לשפה.

Cloud Logging ומיקום הנתונים

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

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

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

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

מגבלות

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

מגבלות

תיאור ערך הערות
המספר המקסימלי של יומנים לכל בקשת OTLP 8192 המספר המקסימלי של logRecords במבנה OTLP resourceLogs. מגבלה.
הגודל המקסימלי של כל בקשה ‫5 MiB מגבלה.
הגודל המקסימלי של LogEntry
שנוצר מרשומה ביומן OTLP		 ‫256 KiB במקרה הצורך, Cloud Logging חותך או משליך נתונים מרשומה ביומן OTLP. מגבלה.
אורך מקסימלי של מפתח מאפיין ‫512 B מפתחות תוויות גדולים מדי נחתכים כשרשומת היומן של OTLP מומרת ל-LogEntry. מגבלה.
האורך המקסימלי של ערך מאפיין ‫64 KiB ערכי תוויות גדולים מדי כשרשומת היומן של OTLP מומרת ל-LogEntry. מגבלה.
עומק הקינון המקסימלי של מאפיינים 5 מאפיינים שחורגים מהמגבלה הזו נחתכים כשרשומת היומן של OTLP מומרת ל-LogEntry.
מספר הבייטים המקסימלי של נתוני יומן שמועברים לדקה

‫2.4 GB באזורים הבאים: asia-east1, asia-northeast1, asia-southeast1, asia-south1, europe-west1, europe-west2, europe-west3, europe-west4, us-central1, us-east4, us-west1.

‫300 MB לכל שאר האזורים.

 מכסה.

התנהגות

  • אם מוגדרים גם מספר החומרה וגם טקסט החומרה של OpenTelemetry, המערכת משתמשת במספר החומרה כדי לקבוע את רמת החומרה של Cloud Logging. אם רשומת ה-OTLP לא מכילה מידע על חומרת הבעיה, רמת החומרה ב-Cloud Logging מוגדרת ל-DEFAULT.

  • כשרישום OTLP מכיל מפתחות מאפיינים כפולים, המערכת שומרת את המפתח הראשון ומשליכה את המאפיינים עם המפתחות הכפולים.

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

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