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

במאמר הזה מוסבר איך Google Cloud Observability קובע את השדות של LogEntry מרשומת היומן של OTLP, כשהרשומה הזו נשלחת אל Google Cloud באמצעות Telemetry API.

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

המבנה הכללי של נתוני יומן בפורמט 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.

איך מוגדרים השדות של LogEntry

‫Google Cloud Observability משתמש בכללים הבאים כדי לקבוע את הערכים של השדות LogEntry:

שדה LogEntry
(שמות מהפניה ל-HTTP)		 איך המערכת קובעת את ערך השדה
logName

המערכת משתמשת בערך של השדה event_name ב-LogRecord של OTLP. אם השדה הזה לא קיים או לא מוגדר, המערכת משתמשת ברשימה הבאה של מאפייני רשומות ביומן של OpenTelemetry לפי סדר עדיפויות כדי לקבוע את שם היומן:

  • log.name
  • gcp.log.name
  • log_name
  • gcp.log_name
  • logging.googleapis.com/logName
  • service.name
  • gcp.service.name
  • service_name
  • gcp.service_name
  • event.name
  • gcp.event.name
  • event_name
  • gcp.event_name

שמות היומנים חייבים להיות בטוחים לשימוש בכתובות URL, אחרת הם מקודדים ככתובות URL במהלך ההטמעה.
resource המערכת משתמשת במידע שמוגדר בשדה resource או מסיקה את המשאב. פרטים נוספים זמינים במאמר מיפוי מאפייני OTLP לסוגי משאבים.
timestamp

כדי לקבוע את הערך של timestamp, המערכת משתמשת ברשימה הבאה של שדות רשומות ביומן של OpenTelemetry, לפי סדר העדיפות:

  • ‫time_unix_nano כשהערך שונה מאפס.
  • ‫observed_time_unix_nano כשהערך שונה מאפס.
  • הזמן שבו הרשומה ביומן נטמעה.

תקופת השמירה של קטגוריית היומנים שבה מאוחסנים הנתונים קובעת את חותמת הזמן הישנה ביותר שאפשר להטמיע. מידע נוסף זמין במאמר מכסות ב-Cloud Logging.
receiveTimestamp הגדרת השעה שבה LogEntry נטמע.
severity המערכת ממפה את רמת החומרה של OpenTelemetry ברשומת היומן לרמת החומרה של Cloud Logging. לפרטים נוספים, קראו את הקטע השדה Severity.
httpRequest

המערכת ממפה את המאפיינים של gcp.http_request ברשומת היומן לשדות מקבילים ב-LogEntry. המערכת מקבלת את המאפיינים האלה כמאפיינים מובְנים או כמחרוזת JSON. למידע נוסף, קראו על השדה HttpRequest.
labels המערכת מגדירה את השדה הזה באמצעות ערכי המאפיינים של רשומת היומן. מידע נוסף זמין בקטע שדה התוויות.
trace המערכת מגדירה את השדה הזה לערך מהשדה traceId של רשומת היומן. הערך חייב להיות מחרוזת הקסדצימלית תקינה באורך 32 תווים, אחרת הרשומה תידחה.
spanId המערכת מגדירה את השדה הזה לערך מהשדה spanId של רשומת היומן. הערך חייב להיות מחרוזת הקסדצימלית תקינה באורך 16 תווים, אחרת הרשומה תידחה.
traceSampled המערכת מגדירה את השדה הזה על סמך הביט הכי פחות משמעותי מהשדה flags של רשומת היומן. אם הביט הכי פחות משמעותי שווה ל-1, השדה הזה מוגדר ל-true. אחרת, הוא נשאר לא מוגדר.
sourceLocation המערכת מגדירה את השדה הזה לערכים מהמאפיינים Code של רשומת היומן. מידע נוסף זמין במאמר השדה SourceLocation.
split לא מוגדר.
apphub
apphubDestination
apphubSource
 לא מוגדר.
otel בשדות בנתוני היומן של OTLP שאין להם שדה מקביל ב-LogEntry, המערכת ממירה את סוגי הנתונים ומוסיפה את הנתונים שהומרו לשדה otel. למידע נוסף, ראו שדה Otel.
operation

המערכת ממפה את המאפיינים של gcp.operation ברשומת היומן לשדות מקבילים ב-LogEntry. מידע נוסף זמין בקטע השדה Operation.
Payload המערכת מגדירה את המטען הייעודי (payload) על ידי המרת הגוף של רשומת היומן לסוג מטען ייעודי מתאים. מידע נוסף זמין במאמר השדה Payload.

השדה HttpRequest

‫Google Cloud Observability ממפה מאפייני OTLP שרלוונטיים לבקשות HTTP לשדות של LogEntry. בקטעים הבאים מוסבר איך המערכת ממפה מאפיינים שטוחים ומאפיינים בתצוגת עץ.

מאפיינים שטוחים

בטבלה הבאה מתואר איך Google Cloud Observability ממפה מאפיינים שטוחים שחלים על בקשות HTTP לשדות LogEntry. לדוגמה, הערך מהמאפיין http.request.method: "GET", מוגדר כערך של השדה httpRequest.requestMethod ברשומת יומן:

צמד מפתח/ערך של OpenTelemetry
LogRecord.attribute
.		 הערך שמאוחסן בשדה
LogEntry הבא
(שמות מהפניה ב-HTTP)		 סוג הפריט שאושר
http.request.method httpRequest.requestMethod מחרוזת
url.full
http.url 		httpRequest.requestUrl מחרוזת
http.request.body.size httpRequest.requestSize מחרוזת, מספר שלם
http.response.status_code httpRequest.status מחרוזת, מספר שלם
http.response.body.size httpRequest.responseSize מחרוזת, מספר שלם
user_agent.original
http.user_agent 		httpRequest.userAgent מחרוזת
client.address remoteIp מחרוזת
server.address serverIp מחרוזת
referrer httpRequest.referer מחרוזת
latency httpRequest.latency מחרוזת, מספר שלם
cacheLookup httpRequest.cacheLookup בוליאני
cacheHit httpRequest.cacheHit בוליאני
cacheValidatedWithOriginServer httpRequest.cacheValidatedWithOriginServer בוליאני
cacheFillBytes httpRequest.cacheFillBytes מחרוזת, מספר שלם
network.protocol.version
protocol 		httpRequest.protocol מחרוזת

מאפיינים בתצוגת עץ

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

log_record {
  attributes: {
    gcp.http_request {
      "requestMethod": "GET",
      "requestUrl": "some-URL",
    }
    http_request {
      "requestMethod": "GET",
    }
  }
}

הפורמט של השדה gcp.http_request יכול להיות מאפיינים מובְנים בתצוגת עץ או מחרוזת JSON של מאפיינים מובְנים.

log_record {
  attributes: {
    gcp.http_request: "{\"requestMethod\": \"GET\", \"requestUrl\": \"some-URL\"}"
  }
}

בטבלה, המאפיינים בתצוגת עץ מוצגים באמצעות סוגריים מסולסלים. לדוגמה, gcp.http_request {requestMethod} פירושו שהמאפיין gcp.http_request מכיל את המאפיין requestMethod. הערך של המאפיין הפנימי ביותר מוקצה לערך של שדה רשומת היומן:

צמד מפתח/ערך של OpenTelemetry
LogRecord.attribute
.		 הערך שמאוחסן בשדה
LogEntry הבא
(שמות מהפניה ב-HTTP)		 סוג הפריט שאושר
gcp.http_request {requestMethod}
http_request {requestMethod} 		httpRequest.requestMethod מחרוזת
gcp.http_request {requestUrl}
http_request {requestUrl} 		httpRequest.requestUrl מחרוזת
gcp.http_request {requestSize}
http_request {requestSize} 		httpRequest.requestSize מחרוזת, מספר שלם
gcp.http_request {status}
http_request {status} 		httpRequest.status מחרוזת, מספר שלם
gcp.http_request {responseSize}
http_request {responseSize} 		httpRequest.responseSize מחרוזת, מספר שלם
gcp.http_request {userAgent}
http_request {userAgent} 		httpRequest.userAgent מחרוזת
gcp.http_request {remoteIp}
http_request {remoteIp} 		httpRequest.remoteIp מחרוזת
gcp.http_request {serverIp}
http_request {serverIp} 		httpRequest.serverIp מחרוזת
gcp.http_request {referer}
http_request {referrer} 		httpRequest.referer מחרוזת
gcp.http_request {latency}
http_request {latency} 		httpRequest.latency מחרוזת, מספר שלם
gcp.http_request {cacheLookup}
http_request {cacheLookup} 		httpRequest.cacheLookup בוליאני
gcp.http_request {cacheHit}
http_request {cacheHit} 		httpRequest.cacheHit בוליאני
gcp.http_request {
cacheValidatedWithOriginServer}
http_request {
cacheValidatedWithOriginServer} 		httpRequest.cacheValidatedWithOriginServer בוליאני
gcp.http_request {cacheFillBytes}
http_request {cacheFillBytes} 		httpRequest.cacheFillBytes מחרוזת, מספר שלם
gcp.http_request {protocol}
http_request {protocol} 		httpRequest.protocol מחרוזת

שדה התוויות

כדי לקבוע אילו תוויות לצרף לרשומה ביומן, המערכת מבצעת את הפעולות הבאות:

  1. הוא מסיר מרשומת היומן של OTLP את כל המאפיינים שמופו לשדות ספציפיים של LogEntry.

    לדוגמה, נניח שהמאפיינים הבאים מצורפים לרשומת יומן:

    attributes: {
    "log_array_attr: ["value1", "value2"],
    "log_json_attr": {"json_key": "json_value"}
    "log-string-attr": "string",
    "code.file.path": "my-file.cc",
    "code.function.name: "my-func",
    "code.line.number": 123,
    "gcp.http_request": {
        "requestMethod": "GET",
        "requestUrl": "my-URL",
  },
}

    אחרי שמסירים שדות שממופים לשדות ספציפיים ב-LogEntry, נשארים השדות הבאים:

    attributes: {
    "log_array_attr: ["value1", "value2"],
    "log_json_attr": {"json_key": "json_value"}
    "log-string-attr": "string",
}

  2. אם מאפיין מכיל מערך או רכיבי JSON, המערכת ממירה את הערך למחרוזת.

    לדוגמה, כך LogEntry מייצג את המאפיינים הקודמים:

    labels: {
    "log_array_attr": "[\"value1\",\"value2\"]",
    "log_json_attr": "{\"json_key\":\"json_value\"}",
    "log-string-attr": "string",
}

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

השדה "פעולה"

‫Google Cloud Observability ממפה את מאפייני ה-OTLP שרלוונטיים לפעולה לשדה operation של LogEntry. בקטעים הבאים מוסבר איך המערכת ממפה את המאפיינים בתצוגת עץ.

המאפיין gcp.operation חייב להכיל סוגים של מפתח/ערך. אין תמיכה בשמות מאפיינים שטוחים. בדוגמה הבאה מוצגת רשומת יומן שהמאפיין gcp.operation שלה מכיל ארבעה צמדי מפתח/ערך:

log_record {
  attributes: {
    gcp.operation {
      "id": "abc123",
      "producer": "my_producer",
      "first": "true",
      "last": "false",
    }
  }
}

בטבלה הבאה מוסבר איך Google Cloud Observability ממפה את gcp.operation ל-LogEntry:

צמד מפתח/ערך של OpenTelemetry
LogRecord.attribute.operation
.		 הערך שמאוחסן בשדה הפעולה
LogEntry הבא
 סוג הפריט שאושר
id id מחרוזת
producer
 httpRequest.requestUrl מחרוזת
first first בוליאני
last last בוליאני

שדה Otel

בשדות בנתוני היומן של OTLP שאין להם שדה מקביל ב-LogEntry, המערכת ממירה את סוגי הנתונים ומוסיפה את הנתונים שהומרו לשדה otel. לדוגמה, בשדה otel מאוחסנים מאפיינים מהשדות resource,‏ scope ו-entity.

המערכת משתמשת בכללים הבאים כדי להמיר את סוגי הנתונים של OpenTelemetry לסוגי Value של protobuf:

סוג OpenTelemetry סוג protobuf
string string
boolean bool
integer double
float double
Array ListValues
KeyValueList Struct

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

שדה מטען ייעודי (payload)

סוג הנתונים של השדה logRecord.body ב-OTLP קובע את המבנה של המטען הייעודי (payload) של LogEntry:

  • ‫string: המערכת מעתיקה את המחרוזת לשדה LogEntry.textPayload.

  • ‫Array: המערכת יוצרת מחרוזת של רכיבי המערך תוך שמירה על שורות חדשות. לאחר מכן, הוא מעתיק את המחרוזת לשדה LogEntry.textPayload.

  • ‫KeyValueList: המערכת ממירה את הזוגות האלה ל-JSON ואז מאכלסת את השדה LogEntry.jsonPayload, עם המגבלות הבאות:

    • אם רשומת OTLP מכילה מפתחות מאפיינים כפולים, המערכת שומרת את המפתח הראשון ומוחקת מאפיינים עם מפתחות כפולים.
    • כשרמת ההיררכיה של צמד JSON גדולה מ-5, המערכת חותכת את התוכן לרמה 5.

שדה חומרה

בקטע הזה מוסבר איך Google Cloud Observability ממפה את שדות החומרה של OpenTelemetry לרמות החומרה של Cloud Logging. ב-OpenTelemetry מוגדרים מספר חומרה וטקסט חומרה. logs.proto מגדיר את מספרי החומרה.

‫Google Cloud Observability קובע את רמת החומרה של הרישום ביומן לפי מספר החומרה של OpenTelemetry, אם הוא מוגדר. אחרת, נעשה שימוש בטקסט של רמת החומרה. אם אף אחת מהן לא מוגדרת, רמת החומרה של הרישום ביומן מוגדרת ל-DEFAULT.

מספר חומרת OpenTelemetry
טיפוס בן מנייה (ערך)		 טקסט חומרת הבעיה ב-OpenTelemetry
(הבדיקות לא תלויות-רישיות)		 רמת החומרה ב-Cloud Logging
טיפוס בן מנייה (ערך)
SEVERITY_NUMBER_UNSPECIFIED (0) "default"
לא מוגדר		 DEFAULT (0)
SEVERITY_NUMBER_TRACE (1)
SEVERITY_NUMBER_TRACE2 (2)
SEVERITY_NUMBER_TRACE3 (3)
SEVERITY_NUMBER_TRACE4 (4)		 "trace"
"trace2"
"trace3"
"trace4"		 DEBUG (100)
SEVERITY_NUMBER_DEBUG (5)
SEVERITY_NUMBER_DEBUG2 (6)
SEVERITY_NUMBER_DEBUG3 (7)
SEVERITY_NUMBER_DEBUG4 (8)		 "debug"
"debug2"
"debug3"
"debug4"		 DEBUG (100)
SEVERITY_NUMBER_INFO (9)
SEVERITY_NUMBER_INFO2 (10)		 "info"
"info2"		 INFO (200)
SEVERITY_NUMBER_INFO3 (11)
SEVERITY_NUMBER_INFO4 (12)		 "notice"
"info3"
"info4"		 NOTICE (300)
SEVERITY_NUMBER_WARN (13)
SEVERITY_NUMBER_WARN2 (14)
SEVERITY_NUMBER_WARN3 (15)
SEVERITY_NUMBER_WARN4 (16)		 "warning"
"warn"
"warn2"
"warn3"
"warn4"		 ‫WARNING (400)
SEVERITY_NUMBER_ERROR (17)
SEVERITY_NUMBER_ERROR2 (18)
SEVERITY_NUMBER_ERROR3 (19)
SEVERITY_NUMBER_ERROR4 (20)		 "error"
"error2"
"error3"
"error4"		 ERROR (500)
SEVERITY_NUMBER_FATAL (21)
SEVERITY_NUMBER_FATAL2 (22)		 "critical"
"fatal"
"fatal2"		 CRITICAL (600)
SEVERITY_NUMBER_FATAL3 (23) "alert"
"fatal3"		 ALERT (700)
SEVERITY_NUMBER_FATAL4 (24) "emergency"
"fatal4"		 EMERGENCY (800)

השדה SourceLocation

‫Google Cloud Observability ממפה את ערכי Code הבאים של OTLP ישירות לשדות של LogEntry. המיפוי הזה אפשרי כי המאפיינים האלה של OpenTelemetry זהים מבחינה סמנטית למושגים של Cloud Logging.

צמד מפתח/ערך של OpenTelemetry
LogRecord.attribute
.		 הערך שמאוחסן בשדה
LogEntry הבא
(שמות מהפניה ב-HTTP)		 סוג הפריט שאושר
code.file.path: Value sourceLocation.file מחרוזת
code.function.name: Value sourceLocation.function מחרוזת
code.function.number: Value sourceLocation.line מחרוזת, מספר שלם

מגבלות

בקטע הזה מתוארות המגבלות. בנוסף, מוסבר איך 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. מגבלה.
עומק מקסימלי של מאפיינים מקוננים 20 בקשות עם מאפיינים שחורגים מהמגבלה הזו נדחות כשרשומת היומן של OTLP מומרת ל-LogEntry.
המספר המקסימלי של בייטים להטמעת יומנים בדקה

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

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

 מכסה.

התנהגות

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

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

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

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

הגדרת Google Cloud Observability לשימוש במיפויים של הייצואן

ב-Google Cloud Observability וב Google Cloud מייצא ל-Cloud Logging משתמשים בכללים שונים כדי ליצור אובייקטים של LogEntry מנתוני יומנים בפורמט OTLP. לדוגמה, Google Cloud Observability מאכלס את השדה otel, אבל המייצאים לא.

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

  1. מוסיפים את המאפיין gcp.use_legacy_mapping למשאב שנכלל בבקשה. מידע נוסף זמין במאמר הוספה או מחיקה של מאפיינים.

    כשמגדירים את המאפיין הזה, קורים הדברים הבאים:

    1. השדה otel לא מאוכלס.

    2. מאפיינים שמתחילים ב-gcp נמחקים, חוץ מהמאפיינים הבאים:

      • gcp.log.name
      • gcp.insert_id

      שני המאפיינים הקודמים ממופים לשדות של LogEntry.

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

  2. מוסיפים למאגר ה-OTLP HTTP מעבדים שמגדירים את תוויות היומן הבאות:

    • ‫instrumentation_scope: מוגדר לערך instrumentation_scope.name.
    • ‫instrumentation_version: מוגדר לערך instrumentation_scope.version.
    • ‫service.name: מוגדר לערך resource.attributes["service.name"].
    • ‫service.namespace: מוגדר לערך resource.attributes["service.namespace"].
    • ‫service.instance.id: מגדירים לערך resource.attributes["service.instance.id"].

    לדוגמה, ראו מעבר למייצא OTLP: מעבדים.