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

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

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

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

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

  • time_unix_nano אם הערך שונה מאפס.
  • observed_time_unix_nano אם הערך שונה מאפס.
  • השעה שבה הרשומה ביומן נקלטה.

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

המערכת ממפה את מאפייני gcp.http_request ברשומה ביומן לשדות המקבילים של LogEntry. מידע נוסף זמין במאמר בנושא השדה HttpRequest.

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

המערכת ממפה את מאפייני gcp.operation ברשומה של היומן לשדות מקבילים של LogEntry. מידע נוסף זמין במאמר בנושא שדה הפעולה.
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 bool
cacheHit httpRequest.cacheHit bool
cacheValidatedWithOriginServer httpRequest.cacheValidatedWithOriginServer bool
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 {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 bool
gcp.http_request {cacheHit}
http_request {cacheHit} 		httpRequest.cacheHit bool
gcp.http_request {
cacheValidatedWithOriginServer}
http_request {
cacheValidatedWithOriginServer} 		httpRequest.cacheValidatedWithOriginServer bool
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 bool
last last bool

שדה Otel

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

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

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

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

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

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

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

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

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

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

שדה מידת החומרה

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

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

מספר חומרת הבעיה ב-OpenTelemetry
Enum (value)		 טקסט חומרת הבעיה ב-OpenTelemetry
(הבדיקות לא תלויות-רישיות)		 רמת החומרה ב-Cloud Logging
Enum (value)
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. מגבלה.
עומק הקינון המקסימלי של מאפיינים 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.

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

‫Google Cloud Observability והכלי לייצוא של Cloud Logging משתמשים בכללים שונים כדי ליצור אובייקטים של LogEntry מנתוני יומן בפורמט OTLP. Google Cloud לדוגמה, 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 collector כדי להגדיר את התוויות הבאות של היומן:

    • ‫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: מעבדים.