סקירה כללית על הטמעת יומנים ב-OTLP

במסמך הזה מוסבר איך להשתמש ב-Telemetry (OTLP) API,‏ telemetry.googleapis.com, כדי להטמיע יומנים בפורמט OTLP ב-Cloud Logging, שם הם מאוחסנים כרשומות יומן. דוגמה מופיעה במאמר כתיבת יומנים בפורמט OTLP ל-Telemetry API.

אפשר גם לשלוח יומנים אל Telemetry API מתוך אפליקציות שמשתמשות ב-SDK או באמצעות OpenTelemetry Collector.

מידע על Telemetry API ליומנים, למדדים ולעקבות זמין במאמר הפניה ל-Telemetry (OTLP) API.

תמיכה בפרוטוקול

נקודת הקצה של OTLP תומכת בכל פרוטוקולי OTLP, כולל http/protobuf, http/json ו-grpc. כשמייצאים מ-OpenTelemetry Collector, אפשר להשתמש בכל אחד מהפרוטוקולים. עם זאת, בגלל חוסר התמיכה ברענון דינמי של אסימונים ברוב כלי הייצוא של SDK, אם אתם מייצאים ישירות מ-SDK, מומלץ להשתמש רק בכלי הייצוא gRPC OTLP ולא בכלי הייצוא HTTP.

חיוב

יכול להיות שתראו שינוי בערכי האחסון והחיוב של Cloud Logging כשמשתמשים ב-Telemetry API כדי להטמיע יומנים. בקשת יומן בפורמט OTLP ב-JSON כוללת את המבנה הכללי הבא:

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

כל פריט בכל מערך logRecords הופך לרשומה אחת ביומן של Cloud Logging. השינויים הכי גדולים בנפח האחסון ובחיוב של Google Cloud הפרויקט מתרחשים כשמתקיימים שני התנאים הבאים:

  • השדה resource מכיל מספר גדול של מאפייני חובה למפתחות ולערכים. מאפייני המשאבים האלה משמשים לקביעת המשאב שבמעקב בLogEntry שמתקבל.

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

  • השדה scopeLogs מכיל מספר גדול של פריטים במערכי logRecords.

כדי לתמוך בהטמעה של יומנים בפורמט OTLP, המבנה של Cloud Logging‏ LogEntry כולל שדה נוסף, otel. מודלי הנתונים של OTLP ו-Cloud Logging לא זהים לחלוטין, ולכן השדה otel מכיל עותק של המשאב, ההיקף והישויות של OTLP מהבקשה הנכנסת של OTLP.

לדוגמה, אם שולחים OTLP resourceLog כמו זה שבהמשך אל Telemetry API, כל רשומה ביומן שמתקבלת מכילה שדה resource (למשאב שבמעקב) ושדה otel, כמו שמוצג בכרטיסיות האחרות:

resourceLog 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

ל-Cloud Logging אין דרך לקשר משאבים אחרים לרשומה ביומן, ולכן צריך להעתיק את כל המידע על משאבי OTLP, היקפים וישויות לכל רשומה ביומן.

השכפול הזה שומר כמה שיותר מידע מהבקשה המקורית ברשומה שמתקבלת ביומן. אבל הכפילות הזו גם אומרת שהשדה otel חוזר על פרטי המשאב שמשמשים גם בשדה monitored-resource (resource) של רשומת היומן. גם השדה resource של רשומת היומן וגם פרטי המשאב ששוכפלו בשדה otel מחויבים.

כשכוללים מספר גדול של רשומות יומן בבקשת OTLP, צריך להעתיק את פרטי OTLP לכל רשומת יומן שמתקבלת, לשדות resource ו-otel. כשכוללים מספר גדול של logRecords OTLP בבקשה, מספר השדות resource שניתנים לחיוב ברשומות היומן גדל באופן יחסי למספר ה-OTLP logRecords לכל resource לכל בקשה.

כדי לצמצם את כמות המידע הנוסף שנשמר, מומלץ לשלוח בקשה אחת לכל פריט logRecord.

מגבלות ומכסות

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

המכסות והמגבלות של Cloud Logging חלות גם כשמשתמשים ב-Telemetry API להוספת יומנים.