העברת כלי איסוף לשימוש בייצוא OTLP

‫Telemetry (OTLP) API הוא הטמעה של OpenTelemetry Protocol. התמיכה ב-OTLP מאפשרת לכם להוסיף מייצאים כלליים otlphttp ו-otlp_grpc/otlp_logs להגדרות של האוסף, וכך להימנע ממייצאים ספציפיים לספק. אפליקציות יכולות לשלוח נתוני יומן, מדדים ונתוני מעקב אל Telemetry API.

המדריך הזה רלוונטי אם בהגדרות של המלקט נעשה שימוש בgooglecloud exporter או ב-googlemanagedprometheus exporter:

כדי לבצע מיגרציה של נתוני ייצוא ל-OTLP:

  1. הפעלת Telemetry API
  2. איך נותנים הרשאה לחשבון השירות של הכלי לאיסוף נתונים
  3. הגדרה של משתנה הסביבה GOOGLE_CLOUD_PROJECT
  4. הוספת התוסף googleclientauth
  5. הוספת כלי הייצוא otlphttp ו-otlp_grpc/otlp_logs
  6. הוספת מעבדים
  7. עדכון צינורות עיבוד נתונים של שירותים
  8. בדיקה של הגדרת החשבון
  9. העברה של לוחות בקרה ומדיניות התראות
  10. הסרה של כלי ייצוא ספציפיים לספקים

הפעלת Telemetry API

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

gcloud services enable telemetry.googleapis.com

אישור חשבון השירות של הכלי לאיסוף נתונים

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

התפקידים הנדרשים

כדי לוודא שלחשבון השירות שמריץ את האוסף יש את ההרשאות הנדרשות לשליחת נתוני יומן, מדדים ומעקב, צריך לבקש מהאדמין להקצות לחשבון השירות שמריץ את האוסף בפרויקט את תפקידי ה-IAM הבאים:

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

ההרשאות הנדרשות

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

  • logging.logEntries.create
  • monitoring.timeSeries.create
  • telemetry.traces.write
  • serviceusage.services.use

חשבון שירות ב-Kubernetes

אם פורסים את האוסף ב-Google Kubernetes Engine ‏ (GKE) באמצעות איחוד זהויות של עומסי עבודה ל-GKE, צריך להעניק את התפקידים הנדרשים לחשבון השירות של Kubernetes.

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

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

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

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

חשבון שירות לאיחוד זהויות של עומסי עבודה ל-GKE

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

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

חשבון שירות אחר

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

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

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

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

הוספת התוסף googleclientauth

מוסיפים את התוסף googleclientauth להגדרת האוסף. ‫Telemetry API הוא ממשק API לצרכנים, ולכן צריך לציין בו גם את Google Cloud הפרויקט וגם את המכסה בפרויקט. התוצאה אמורה להיראות כך:

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

הוספת כלי הייצוא otlphttp ו-otlp_grpc/otlp_logs

משתמשים ב-otlphttp exporter כדי לשלוח נתוני מדדים ומעקב בפורמט OTLP לפרויקט, וב-otlp_grpc/otlp_logs exporter כדי לשלוח נתוני יומן. חשוב להגדיר את שני כלי הייצוא באמצעות התוסף googleclientauth.

התוצאה אמורה להיראות כך:

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

במקרה של כלי הייצוא otlp_grpc/otlp_logs, צריך לציין את השדה endpoint באמצעות הפורמט host:port.

הוספת מעבדים

בקטע הזה מפורטים מעבדים שצריך להוסיף לכלי האיסוף. יש מעבדים אחרים שאולי תרצו להשתמש בהם. לדוגמה, הגדרות של Google-Built OpenTelemetry Collector בדרך כלל כוללות את המעבד memory_limiter ומעבד נוסף שמבצע טרנספורמציה של נתוני מדדים. דוגמה מופיעה במאמר בנושא Google-Built OpenTelemetry Collector on GKE.

הוספת מעבד resource/gcp_project_id

מוסיפים resourceמעבד שמקבל מידע עלGoogle Cloud הפרויקט.

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

הוספת מעבד resourcedetection

אם אתם מריצים על Google Cloud, כדאי להוסיף את המעבד resourcedetection. המעבד הזה יכול לגלות באופן אוטומטי מידע על הארכיטקטורה שלכם.

ההגדרה הבאה מחפשת את משתני הסביבה הרגילים של OpenTelemetry, ואז שולחת שאילתה לשרת המטא-נתונים של Google Cloud כדי לאסוף מידע על התשתית שלכם:

  resourcedetection:
    detectors: ["env", "gcp"]

הוספת מעבד batch

כדי לשלוח את נתוני הטלמטריה לפרויקט Google Cloud בצורה יעילה יותר, מומלץ להשתמש במעבד batch.

לדוגמה, קובץ ההגדרות של Google-Built OpenTelemetry Collector כולל את ההגדרות הבאות למעבד של אצווה:

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

הוספת מעבד metricstarttime

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

חובה להוסיף את המעבד הזה אם האוסף מקבל מדדי Prometheus.

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

הוספת מעבד טרנספורמציה

כדי לשמור את מקור המדידה והגרסה בנתוני היומן, צריך להוסיף את המעבד transform הבא:

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

עדכון צינורות שירות

לאחר מכן, מעדכנים את צינורות הנתונים של האוסף כדי להשתמש בייצואנים otlp_grpc/otlp_logs ו-otlphttp. במקרה של נתוני יומן ומעקב, ההוראות האלה מחליפות את כלי הייצוא הנוכחי בכלי הייצוא המתאים של OTLP. ההוראות האלה גורמות לכתיבה כפולה של נתוני המדדים. הגישה הזו מאפשרת לכם לוודא שהכלי לייצוא OTLP שולח נתוני מדדים לפרויקט Google Cloud . בנוסף, אפשר לעדכן תרשימים ומדיניות התראות לפני שמפסיקים את זרמי הנתונים מהכלי המקורי לייצוא.

מבצעים את השינויים הבאים בהגדרות של צינור הנתונים של כלי האיסוף:

  1. מוסיפים את התוסף googleclientauth לרשומה service.

  2. בצינור העיבוד של היומנים, מחליפים את googlecloud/logging ב-otlp_grpc/otlp_logs ואז מוסיפים את המעבדים הבאים לרשימת המעבדים של צינור העיבוד:

    • resource/gcp_project_id
    • transform/otlp_grpc/preserve_instrumentation_source_version
    • ‫resourcedetection (אם הוספתם את מעבד המידע הזה)
    • batch

    ההגדרה הזו מבצעת כתיבה יחידה של נתוני יומן. אם רוצים לבצע כתיבה כפולה של נתוני היומן, מוסיפים את otlp_grpc/otlp_logs exporter לרשימת ה-exporters.

  3. בצינור המדדים, מוסיפים את רכיב ה-otlphttp לרשימת הרכיבים של הצינור לצד רכיב ה-googlemanagedprometheus, ואז מוסיפים את המעבדים הבאים:

    • resource/gcp_project_id
    • metricstarttime
    • ‫resourcedetection (אם הוספתם את מעבד המידע הזה)
    • batch

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

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

    • resource/gcp_project_id
    • ‫resourcedetection (אם הוספתם את מעבד המידע הזה)
    • batch

    ההגדרה הזו מבצעת כתיבה יחידה של נתוני מעקב.

התוצאה של השינויים האלה דומה לתוצאה הבאה:

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

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

אימות ההגדרה

מפעילים מחדש את הפריסה ומוודאים שהייצואנים של otlphttp ושל otlp_grpc/otlp_logs שולחים נתונים לפרויקט Google Cloud . כדי לאמת את ההגדרה:

  • מריצים שאילתה בערכי היומן כדי למצוא שגיאות שקשורות לכתיבת נתוני טלמטריה.
  • אפשר לראות את שיעורי השגיאות עבור Cloud Logging API,‏ Cloud Monitoring API ו-Telemetry API.
  • אפשר להציג סדרות זמנים באמצעות Metrics Explorer.

העברת מרכזי בקרה וכללי מדיניות התראות

כדי לעדכן את התרשימים ולוחות הבקרה:

  1. אם אתם עוקבים אחרי השימוש ב-Cloud Logging API או ב-Cloud Monitoring API באמצעות תרשימים או מדיניות התראות, אתם צריכים ליצור תרשימים או מדיניות התראות נוספים כדי לעקוב אחרי השימוש ב-Telemetry API.

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

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

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

הבדלים בפורמט של מדדים מיוצאים

העדכונים בתרשימים מבוססי-מדדים ובמדיניות ההתראות נדרשים בגלל ההבדלים הבאים בין המדדים שמיוצאים על ידי OTLP לבין המדדים שמיוצאים על ידי googlemanagedprometheus:

  • ב-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. הפעולה הזו שומרת על תאימות לדור קודם, אבל לא על תאימות לדורות הבאים, ולא תוכלו להשתמש בנכסי קוד פתוח שמפנים לשמות המדדים ב-UTF-8.

הסרת כלי ייצוא ספציפיים לספקים

אחרי שמאמתים את מקורות הנתונים החדשים ומעדכנים את לוחות הבקרה ואת כללי ההתראה, מסירים את רכיבי ה-exporter‏ googlecloud/logging ו-googlemanagedprometheus מהגדרות האוסף. יכול להיות שתצטרכו גם להסיר מעבדים ששימשו רק את תהליכי הייצוא שהוסרו מההגדרה.

צריך לעדכן גם את רשימת היצואנים וגם את צינורות העברת הנתונים של השירות.

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

פתרון בעיות

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

נתוני מדדים חסרים או עליות חדות בנתוני מדדים

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

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

הודעות שגיאה לגבי כתיבת סדרות זמן

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

  • הודעת שגיאה שמציינת חוסר התאמה בין ערכים:

    "One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."

    השגיאה הזו מתרחשת אם שלחתם בעבר מדדים של INT64 target_info כי Telemetry API מגדיר את סוג הערך של כל המדדים ל-DOUBLE. הפתרון הטוב ביותר לטווח הארוך הוא למחוק את תיאור המדד של מדדי INT64 target_info. כדי למחוק את המתאר הזה מההיקף של המדד, אפשר להשתמש בסקריפט Golang הזה.

  • הודעת שגיאה שמציינת שכמה מקורות כותבים נתונים של סדרות זמן:

    "One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."

    כדי לפתור את הבעיה, צריך להסיר את googlemanagedprometheus exporter מההגדרה של ה-collector. מידע נוסף זמין במאמר בנושא הסרת כלי ייצוא ספציפיים לספקים.

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