תמיכה ב-OTLP ב-Google Cloud Observability

אתם יכולים להטמיע נתוני יומנים, מדדים ומעקב בפורמט OTLP ב-Google Cloud Observability באמצעות Telemetry (OTLP) API, שמטמיע את פרוטוקול OpenTelemetry. באמצעות ה-API הזה אפשר לאסוף נתוני טלמטריה שלא תלויים בספק מערכות ה-SDK והאוספים של OpenTelemetry, בלי להשתמש ב Google Cloud מייצאים מותאמים אישית.

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

  • נתוני יומן: המרת רשומות יומן של OTLP לרשומות ביומן וניתוב שלהן לאחסון.
  • נתוני מדדים: מיפוי נתוני מדדים לסדרות הזמן של Prometheus ב-Cloud Monitoring.
  • נתוני מעקב: מאחסן מעקבים מבוזרים בפורמט שתואם בדרך כלל ל-OTLP.

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

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

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

אימות

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

במאמר הגדרת אימות מופיעה דוגמה לאימות כשמשתמשים בייצוא ישיר של נתוני מעקב. בדוגמה הזו מוסבר איך להגדיר את הייצוא באמצעות Application Default Credentials ‏ (ADC) של Google Cloud, ולהוסיף לאפליקציה ספריית Google Auth ספציפית לשפה.

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

לדוגמה, אם שולחים ל-Telemetry API מטען ייעודי (payload) של OTLP resourceLogs כמו בדוגמה הבאה, כל רשומת יומן שנוצרת מכילה שדה 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 פועל רק כשמשתמשים ב-OpenTelemetry Collector בגרסה 0.140.0 ואילך.

כשמדדים נקלטים ב-Cloud Monitoring באמצעות OpenTelemetry Collector והמייצא otlphttp, או נשלחים ישירות באמצעות 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.

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

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

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

  • השדה resource של כל span מכיל עותק של הנתונים של resourceSpans.resource.attributes.
  • השדה instrumentation_scope של כל span מכיל עותק של הנתונים של 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 Samples Ingested", אותו מק"ט שמשמש למדדים מהשירות המנוהל של Google Cloud ל-Prometheus.

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

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

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

אתם יכולים להשתמש בדפי ה-Explorer (כמו 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)) נפוצות יותר אמורות לפעול.

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

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

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

בנוסף, חלות המכסות והמגבלות הבאות:

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

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

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

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

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