מעבר אל OTLP exporter

במאמר הזה מוסבר איך לשנות הגדרה של OpenTelemetry Collector שמשתמשת ב-exporter קיים – במקרה הזה, googlemanagedprometheus exporter – כדי להשתמש ב-otlphttp exporter וב-Telemetry (OTLP) API,‏ telemetry.googleapis.com.

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

הפעלת Telemetry API

ה-exporter‏ otlphttp כותב ל-Telemetry API, ולכן צריך להפעיל את ה-API הזה בפרויקט. מפעילים את Telemetry API באמצעות הפקודה הבאה:

gcloud services enable telemetry.googleapis.com

אישור חשבון השירות של Kubernetes

לחשבון השירות של Kubernetes צריכה להיות הרשאה להשתמש ב-Telemetry API. הפקודות הבאות מעניקות לחשבון השירות של Kubernetes את תפקיד ניהול הזהויות והרשאות הגישה (IAM) הנדרש. הפקודות האלה מניחות שאתם משתמשים באיחוד זהויות של עומסי עבודה ל-GKE:

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
  --role=roles/telemetry.metricsWriter \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

מחליפים את המשתנה PROJECT_ID במזהה הפרויקט ב- Google Cloud .

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

  • מחליפים את שם חשבון השירות gmp-test-sa בחשבון השירות שלכם.
  • מריצים את הפקודה כדי להעניק את התפקיד roles/telemetry.metricsWriter.

הגדרת משתנה הסביבה PROJECT_ID

מגדירים את משתנה הסביבה PROJECT_ID בפריסת האוסף. התוצאה אמורה להיראות כך:

env:
- name: PROJECT_ID
  value: PROJECT_ID

מאתרים את כלי הייצוא שרוצים להחליף.

בקובץ התצורה, מאתרים את כלי הייצוא ואת השירות שמשתמש בכלי הייצוא:

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

הוספת הגדרות אישיות לייצוא של otlphttp

בשלב הזה מוסיפים את רכיב otlphttp לייצוא ואת רכיב metricstarttime לעיבוד להגדרות. היצואן הנוסף הזה גורם לאוסף לכתוב את המדדים פעמיים.

  • אם אתם משתמשים במדדים מקוריים של OTLP, כתיבה כפולה לא גורמת לבעיה כי המבנה של מתארי המדדים שנוצרים על ידי שתי השיטות שונה. אלה מדדים נפרדים.
  • אם אתם משתמשים במדדים של Prometheus, תראו התנגשויות עד שתסירו את googlemanagedpromethus exporter.

ההגדרה המעודכנת נראית כך:

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

אחרי שכותבים את המדדים פעמיים, מעדכנים את לוחות הבקרה ואת מדיניות ההתראות כדי להשתמש בשמות המדדים החדשים שנוצרו על ידי כלי הייצוא otlphttp. הכלי לייצוא otlphttp לא משנה את השם של המדדים לפורמט Prometheus, באמצעות החלפה של רווחים בקו תחתון.

הסרת ההגדרה של הכלי הקודם לייצוא

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

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

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

אם השתמשתם בייצוא googlemanagedprometheus רק לנתוני מדדים של Prometheus, כשעוברים לייצוא OTLP, לוחות הבקרה ומדיניות ההתראות הקיימים ימשיכו לפעול.

עם זאת, אם השתמשתם בgooglemanagedprometheus כלי הייצוא כדי לאסוף ולשלוח נתונים שהופקו במקור באמצעות OTLP, או אם ביצעתם גירוד של מדדי Prometheus עם תווים בקידוד UTF-8, תצטרכו לעדכן את לוחות הבקרה וההתראות כדי להשתמש בשם המדד בקידוד UTF-8.

הסיבה לכך היא ההבדלים הבאים בין מדדים שמיוצאים באמצעות OTLP לבין מדדים שמיוצאים באמצעות googlemanagedprometheus exporter:

  • ב-Telemetry API אפשר להשתמש בנקודה (.) ובסלאש (/) בשמות של מדדים. הכלי googlemanagedprometheus exporter ממיר את כל המופעים של התווים האלה לתו קו תחתון (_). לדוגמה, מדד OTLP בשם prometheus.googleapis.com/foo.bar/gauge מיוצא כלשונו על ידי כלי הייצוא של OTLP, אבל מיוצא בתור prometheus.googleapis.com/foo_bar/gauge על ידי כלי הייצוא googlemanagedprometheus.

    כשמבצעים הטמעה של המדדים, Cloud Monitoring יוצר מתארי מדדים על סמך השמות. ההבדל באופן הטיפול בנקודה (.) ובקו נטוי (/) בנתיבי ההטמעה גורם לכך שמתארי המדדים שמתקבלים שונים בין מדדים שמוטמעים באמצעות כלי הייצוא googlemanagedprometheus לבין מדדים שמוטמעים באמצעות כלי הייצוא otlphttp. אם משתמשים בשני נתיבי ההטמעה, מקבלים שני סטים של מדדים. כדי לקבל תוצאות מלאות כשמריצים שאילתה, צריך לאחד באופן ידני את התוצאות מהגרסאות של המדדים ב-Prometheus וב-OTLP.

  • ‫Telemetry API לא מוסיף יחידה לשם של מדד אם יש יחידה, ולא מוסיף את הסיומת _total למונים. לכן, מדד שמיוצא כ-prometheus.googleapis.com/foo/counter כשמשתמשים ב-Telemetry API מיוצא כ-prometheus.googleapis.com/foo_seconds_total/counter על ידי googlemanagedprometheus exporter. ההבדל הזה רלוונטי גם לסיומות _total ו-_ratio.

מידע נוסף על ההבדלים בין המדדים זמין במאמר ההבדלים בין כלי הייצוא של googlemanagedprometheus לבין Telemetry API.

מכיוון שכללי השינוי לא חלים על מדדים עם תווים ב-UTF-8, צריך לשכתב את לוחות הבקרה ואת מדיניות ההתראות כדי להשתמש בשמות המדדים החדשים או כדי לאחד את שמות המדדים הישנים והחדשים.

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