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

במסמך הזה מוסבר על השימוש ב-Telemetry (OTLP) API,‏ telemetry.googleapis.com, שמטמיע את OpenTelemetry Protocol. ‫Telemetry API מאפשר לכם להטמיע נתוני יומן, מדדים ומעקב בפורמט OTLP ב-Google Cloud Observability:

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

אם אתם משתמשים ב-Google Kubernetes Engine, אתם יכולים להשתמש ב-Managed OpenTelemetry for GKE במקום לפרוס ולהגדיר ידנית OpenTelemetry Collector שמשתמש ב-Telemetry API.

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

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

אימות

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

הטמעת נתונים ב-OTLP

בקטע הזה מוסבר איך נתוני היומן, המדדים והמעקב מומרים מ-OTLP למבני נתונים של Google Cloud Observability.

הטמעת נתוני יומן

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

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

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

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

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

resourceLogs 

{
  "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 מועתקים לכל רשומה ביומן.

הטמעת נתוני מדדים

פרוטוקול OTLP למדדים של Prometheus פועל רק כשמשתמשים בגרסה 0.140.0 או בגרסה חדשה יותר של OpenTelemetry Collector.

כשמדדים מוזנים ל-Cloud Monitoring באמצעות OpenTelemetry Collector ו-otlphttp exporter, או נשלחים ישירות באמצעות OpenTelemetry SDK, המדדים בפורמט OTLP ממופים למבני מדדים של Cloud Monitoring. כדי לקבל מידע על המיפויים האלה, אפשר לעיין במקורות הבאים:

‫Google Cloud Observability ממיר מדדים לפורמט של סדרת הזמנים של Prometheus. שמות המדדים לא יכולים לכלול דומיין או שהם חייבים לכלול את הדומיין prometheus.googleapis.com. אחרי ההמרה, שם המדד כולל את הקידומת prometheus.googleapis.com ואת הסיומת הנוספת, בהתאם לסוג הנקודה ב-OTLP. מדד Cloud Monitoring שמתקבל הוא בעל המבנה הבא:

prometheus.googleapis.com/{metric_name}/{suffix}

בנוסף, לכל משאב ייחודי של OpenTelemetry, ההמרה מוסיפה מדד target_info שמכיל את כל מאפייני המשאב, למעט service.name, service.instance.id ו-service.namespace.

מכיוון ששמות של מדדים ומפתחות של תוויות ב-Cloud Monitoring לא תומכים ב-UTF-8 מלא, יכול להיות שנתוני מדדים יידחו:

  • שמות של מדדים שלא תואמים לביטוי הרגולרי [a-zA-Z][a-zA-Z0-9_:./-]* יידחו. התווים המיוחדים היחידים שמותרים בשמות של מדדים הם התווים שבקבוצה _:./-.
  • נקודות נתונים שמכילות מאפיינים (כלומר, מפתחות של תוויות) שלא תואמים לביטוי הרגולרי [a-zA-Z_][a-zA-Z0-9_.]* נדחות. התווים המיוחדים היחידים שמותרים במפתחות של תוויות הם אלה שבקבוצה _.. מותר להשתמש בכל התווים המיוחדים בערכי התוויות.

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

הטמעת נתוני מעקב

לא משנה אם משתמשים ב-Telemetry API או ב-Cloud Trace API, נתוני העקבות הנכנסים נשמרים בפורמט שתואם ל-OTLP. עם זאת, מומלץ להשתמש ב-Telemetry API כי הוא מספק מכסות גבוהות יותר של נתונים בהשוואה ל-Cloud Trace API.

זו דוגמה לנתוני Trace שאולי יישלחו מאפליקציה לפרויקט שלכם ב- Google Cloud :

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

כל פריט בכל מערך scopeSpans.spans הופך לטווח מאוחסן יחיד:

  • השדה resource של כל טווח מכיל עותק של נתוני resourceSpans.resource.attributes.
  • השדה instrumentation_scope של כל טווח מכיל עותק של נתוני scopeSpans.scope.
  • כל טווח תואם לרשומה אחת במערך scopeSpans.spans. שדות כמו traceId,‏ spanId ו-kind ממופים לשדות עם שמות דומים בסכימת העקבות.

מידע נוסף זמין במאמרים הבאים:

חיוב

החיוב על נתוני יומן, מדדים ונתוני מעקב שמועברים באמצעות Telemetry API תלוי באות הטלמטריה. מידע מלא זמין בדף החיוב.

חיוב על נתוני יומן

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

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

  • השדה resource מכיל מאפיינים עם קרדינליות גבוהה או מספר גדול של מאפיינים. מאפייני המשאב האלה קובעים את המשאב במעקב ב-LogEntry שמתקבל.
  • השדה scopeLogs מכיל מספר גדול של פריטים במערכי logRecords. השדות scopeLogs.scope מועתקים לשדה otel לכל רשומה ביומן.

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

כדי לצמצם את נפח האחסון, מומלץ:

  • כדי להשליך מאפייני משאב או היקף מיותרים לפני ייצוא הנתונים, אפשר להשתמש במעבד OpenTelemetry Collector, כמו מעבד transform.
  • אם אתם לא צריכים לשמור את המטא-נתונים הנוספים בשדה otel, אתם יכולים להשתמש באפשרות המיפוי מדור קודם, gcp.use_legacy_mapping, כדי למנוע את האכלוס של השדה otel.

חיוב על נתוני מדדים

החיוב על מדדים של OTLP נכלל במק"ט 'דגימות של Prometheus שהועברו', אותו מק"ט שמשמש למדדים מהשירות המנוהל של Google Cloud ל-Prometheus.

חיוב על נתוני מעקב

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

שאילתות על נתוני היומן, המדדים והמעקב

אתם יכולים להשתמש בדפי הכלי לניתוח נתונים – Logs Explorer,‏ Metrics Explorer ו-Trace Explorer – כדי לשלוח שאילתות לנתוני היומן, המדדים והמעקב. אפשר גם להשתמש בדף Observability Analytics כדי לנתח את נתוני היומן והמעקב באמצעות SQL.

הטיפים הבאים יכולים לעזור לכם כשאתם שולחים שאילתות לגבי נתוני המדדים באמצעות Metrics Explorer:

  • חשוב: כשמבצעים שאילתות על שמות של מדדים ומפתחות של תוויות עם תווים מיוחדים שאינם נקודתיים (:) או קו תחתון (_), צריך להוסיף אותם בסוגריים מסולסלים ({}) ובמירכאות ("), בהתאם למפרט UTF-8 של PromQL. לדוגמה, השאילתות הבאות הן שאילתות תקינות:

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • השארת התווית le כשמריצים שאילתה על היסטוגרמות אקספוננציאליות עלולה להחזיר תוצאות לא צפויות. צפוי שהשאילתות הטיפוסיות יותר histogram_quantile(.99, sum by (le) (metric)) יפעלו.

  • יכול להיות שבנסיבות מסוימות, כמו דלתאות דלילות מאוד, לא תתבצע שאילתה תקינה של מדדי הדלתא.

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

המגבלות של Telemetry API חלות על כל סוגי האותות.

חלות גם המכסות והמגבלות הבאות:

  • נתוני יומן: חלות המכסות והמגבלות של Cloud Logging API.

  • נתוני מדדים: חלות עליהם המכסות והמגבלות של Cloud Monitoring API. לדוגמה, למדדים לא יכולות להיות יותר מ-200 תוויות.

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

  • נתוני מעקב: אין מכסות או מגבלות נוספות שחלות.

המאמרים הבאים