Deploy Google-Built OpenTelemetry Collector on Google Kubernetes Engine

במאמר הזה מוסבר איך להפעיל את Google-Built OpenTelemetry Collector ב-Google Kubernetes Engine כדי לאסוף יומנים, מדדים ועקבות של OTLP מאפליקציות עם אינסטרומנטציה, ואז לייצא את הנתונים האלה אל Google Cloud.

לפני שמתחילים

כדי להריץ את Google-Built OpenTelemetry Collector, צריך את המשאבים הבאים:

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  8. אשכול Kubernetes. אם אין לכם אשכול Kubernetes, צריך לפעול לפי ההוראות שבמדריך לתחילת העבודה עם GKE.

  9. כלי שורת הפקודה הבאים:

    • gcloud
    • kubectl

    הכלים gcloud ו-kubectl הם חלק מ-Google Cloud CLI. מידע על התקנת הרכיבים האלה מופיע במאמר ניהול רכיבים של Google Cloud CLI. כדי לראות את הרכיבים של ה-CLI של gcloud שהתקנתם, מריצים את הפקודה הבאה:

            gcloud components list
            

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

אם השבתתם את Workload Identity ב-GKE, אתם יכולים לדלג על הקטע הזה.

כדי לוודא שלחשבון השירות של OpenTelemetry Collector ב-Kubernetes יש את ההרשאות הנדרשות לייצוא טלמטריה, צריך לבקש מהאדמין להקצות לחשבון השירות של OpenTelemetry Collector ב-Kubernetes את תפקידי ה-IAM הבאים בפרויקט:

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

יכול להיות שהאדמין יוכל גם לתת לחשבון השירות של OpenTelemetry Collector ב-Kubernetes את ההרשאות שנדרשות באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

כדי להגדיר את ההרשאות, משתמשים בפקודות הבאות של add-iam-policy-binding:

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/logging.logWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/monitoring.metricWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudtrace.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector

לפני שמריצים את הפקודות, מחליפים את המשתנים הבאים:

  • PROJECT_ID: מזהה הפרויקט.
  • PROJECT_NUMBER: מספר הפרויקט ב- Google Cloud .

פריסת ה-Collector

אפשר לפרוס את צינור הנתונים של Collector ישירות מהדוגמאות שנבדקו ומסופקות על ידי מאגר הנתונים של Self-Managed OTLP Kubernetes Ingestion. אפשר לפרוס ישירות מ-GitHub באמצעות הפקודות הבאות אחרי שמחליפים את PROJECT_ID במזהה הפרויקט Google Cloud :

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export PROJECT_NUMBER=PROJECT_NUMBER
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest.git/k8s/base | envsubst | kubectl apply -f -

לפני שמריצים את הפקודות, מחליפים את המשתנים הבאים:

  • PROJECT_ID: מזהה הפרויקט.
  • PROJECT_NUMBER: המזהה המספרי של הפרויקט.

הגדרת האספן

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

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

הגדרות של כלי האיסוף שסופקו

אפשר למצוא את הגדרת ה-Collector לסביבות Kubernetes במאגר otlp-k8s-ingest:

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

exporters:
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace using OTLP http/proto
  # The otlp exporter could also be used to send them using OTLP grpc
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    # Use the googleclientauth extension to authenticate with Google credentials
    auth:
      authenticator: googleclientauth


extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  googleclientauth:


processors:
  filter/self-metrics:
    metrics:
      include:
        match_type: strict
        metric_names:
        - otelcol_process_uptime
        - otelcol_process_memory_rss
        - otelcol_grpc_io_client_completed_rpcs
        - otelcol_googlecloudmonitoring_point_count
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  k8sattributes:
    extract:
      metadata:
      - k8s.namespace.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name
      - k8s.replicaset.name
      - k8s.node.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.start_time
    passthrough: false
    pod_association:
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.uid
    - sources:
      - from: connection

  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)

  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform/collision:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  # The relative ordering of statements between ReplicaSet & Deployment and Job & CronJob are important.
  # The ordering of these controllers is decided based on the k8s controller documentation available at
  # https://kubernetes.io/docs/concepts/workloads/controllers.
  # The relative ordering of the other controllers in this list is inconsequential since they directly
  # create pods.
  transform/aco-gke:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["top_level_controller_type"], "ReplicaSet") where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.replicaset.name"]) where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_type"], "Deployment") where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.deployment.name"]) where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_type"], "DaemonSet") where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.daemonset.name"]) where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_type"], "StatefulSet") where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.statefulset.name"]) where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_type"], "Job") where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.job.name"]) where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_type"], "CronJob") where resource.attributes["k8s.cronjob.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.cronjob.name"]) where resource.attributes["k8s.cronjob.name"] != nil

  # When sending telemetry to the GCP OTLP endpoint, the gcp.project_id resource attribute is required to be set to your project ID.
  resource/gcp_project_id:
    attributes:
    - key: gcp.project_id
      # MAKE SURE YOU REPLACE THIS WITH YOUR PROJECT ID
      value: ${GOOGLE_CLOUD_PROJECT}
      action: insert
  # The metricstarttime processor is important to include if you are using the prometheus receiver to ensure the start time is set properly.
  # It is a no-op otherwise.
  metricstarttime:
    strategy: subtract_initial_point

receivers:
  # This collector is configured to accept OTLP metrics, logs, and traces, and is designed to receive OTLP from workloads running in the cluster.
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  - googleclientauth
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - metricstarttime
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - batch
      receivers:
      - otlp
    metrics/self-metrics:
      exporters:
      - googlemanagedprometheus
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    traces:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: http://${env:MY_POD_IP}:14317
              insecure: true

יצואנים

ההגדרות של Collector כוללות את האקספורטרים הבאים:

  • googlecloud exporter, for logs and traces. כלי הייצוא הזה מוגדר עם שם יומן ברירת מחדל.

  • googlemanagedprometheus exporter, למדדים. לא צריך להגדיר את הכלי הזה לייצוא, אבל יש אפשרויות הגדרה. מידע על אפשרויות ההגדרה של googlemanagedprometheus exporter זמין במאמר תחילת העבודה עם OpenTelemetry Collector במסמכי התיעוד של השירות המנוהל של Google Cloud ל-Prometheus.

מעבדים

ההגדרה של Collector כוללת את המעבדים הבאים:

  • batch: ההגדרה היא לשליחת בקשות טלמטריה בקבוצות, עם Google Cloud מספר הרשומות המקסימלי לכל בקשה, או עם Google Cloud המרווח המינימלי של כל 5 שניות (המוקדם מביניהם).

  • memory_limiter: מגביל את השימוש בזיכרון של כלי האיסוף כדי למנוע קריסות בגלל חוסר זיכרון. לשם כך, הכלי משמיט נקודות נתונים כשהמגבלה נחצית.

  • resourcedetection: מזהה באופן אוטומטי תוויות של משאבים כמו project_id ו-cluster_name. Google Cloud

  • k8sattributes: מיפוי אוטומטי של מאפייני משאבי Kubernetes לתוויות טלמטריה.

  • transform: משנה את השם של תוויות מדדים שמתנגשות עם תוויות במשאבים Google Cloudשנמצאים במעקב.

מקלטים

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

רכיבים זמינים

ה-OpenTelemetry Collector שנוצר על ידי Google מכיל את הרכיבים שרוב המשתמשים יצטרכו כדי להפעיל חוויה עשירה ב-Google Cloud Observability. רשימה מלאה של הרכיבים הזמינים מופיעה בקטע Components במאגר opentelemetry-operations-collector.

כדי לבקש שינויים או תוספות לרכיבים הזמינים, צריך להגיש בקשה להוספת תכונה במאגר opentelemetry-operations-collector.

יצירת טלמטריה

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

אם כבר יש לכם אפליקציה שמוגדרת עם OpenTelemetry SDK, אתם יכולים להפנות את האפליקציה לנקודת הקצה של Collector.

כדי לפרוס את האפליקציה לדוגמה, מריצים את הפקודה הבאה:

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/app.yaml

כדי להפנות אפליקציות קיימות שמשתמשות ב-OpenTelemetry SDK לנקודת הקצה של Collector, מגדירים את משתנה הסביבה OTEL_EXPORTER_OTLP_ENDPOINT לערך http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317.

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

צפייה בטלמטריה

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

הצגת המדדים

הכלי Google-Built OpenTelemetry Collector אוסף מדדים של Prometheus שאפשר לראות באמצעות Metrics Explorer. המדדים שנאספים תלויים במכשיר המדידה של האפליקציה, אבל כלי האיסוף ש-Google יצרה גם כותב כמה מדדים עצמיים.

כדי לראות את המדדים שנאספו על ידי Google-Built OpenTelemetry Collector:
  1. נכנסים לדף  Metrics explorer במסוף Google Cloud :

    כניסה אל Metrics Explorer

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

  2. בסרגל הכלים של מסוף Google Cloud , בוחרים את Google Cloud הפרויקט. בהגדרות של מרכז האפליקציות, בוחרים את הפרויקט המארח של מרכז האפליקציות או את פרויקט הניהול של התיקייה לניהול אפליקציות.
  3. ברכיב Metric, מרחיבים את התפריט Select a metric, כותבים Prometheus Target בשורת הסינון ומשתמשים בתפריטי המשנה כדי לבחור סוג ספציפי של משאב ומדד:
    1. בתפריט Active resources בוחרים באפשרות Prometheus Target.
    2. כדי לבחור מדד, משתמשים בתפריטים Active metric categories ו-Active metrics. למדדים שנאספים על ידי Google-Built OpenTelemetry Collector יש את הקידומת prometheus.googleapis.com.
    3. לוחצים על אישור.
  4. כדי להוסיף מסננים שמסירים סדרות זמן מתוצאות השאילתה, משתמשים ברכיב Filter.

  5. מגדירים את אופן התצוגה של הנתונים.

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

    כשמודדים ערכים מסוג integer או double, כמו במדדים מסוג counter, הכלי Metrics Explorer מסכם באופן אוטומטי את כל סדרות הזמנים. כדי לשנות את ההתנהגות הזו, מגדירים את התפריט הראשון של הערך Aggregation (צבירה) לNone (ללא).

    מידע נוסף על הגדרת תרשים זמין במאמר איך בוחרים מדדים כשמשתמשים ב-Metrics Explorer.

הצגת העקבות

כדי להציג את נתוני העקבות:

  1. נכנסים לדף Trace explorer במסוף Google Cloud :

    כניסה אל Trace explorer

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

  2. בסרגל הכלים של מסוף Google Cloud , בוחרים את Google Cloud הפרויקט. בהגדרות של מרכז האפליקציות, בוחרים את הפרויקט המארח או את פרויקט הניהול של מרכז האפליקציות.
  3. בקטע הטבלה בדף, בוחרים שורה.
  4. בתרשים גאנט בחלונית Trace details, בוחרים יחידה לוגית למעקב.

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

  5. כדי לראות את היומנים שמשויכים למעקב הזה, בוחרים בכרטיסייה יומנים ואירועים.

    בכרטיסייה מוצגים יומנים בודדים. כדי לראות את הפרטים של הרשומה ביומן, מרחיבים את הרשומה. אפשר גם ללחוץ על הצגת יומנים כדי לראות את היומן באמצעות Logs Explorer.

מידע נוסף על השימוש בכלי Cloud Trace Explorer זמין במאמר חיפוש עקבות ועיון בהם.

הצגת רישומי היומן

בכלי Logs Explorer אפשר לבדוק את היומנים, וגם לראות את העקבות המשויכים, אם הם קיימים.

  1. במסוף Google Cloud , נכנסים לדף Logs Explorer:

    כניסה אל Logs Explorer

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

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

  3. לוחצים על Traces ברשומה ביומן עם הודעת מעקב, ואז בוחרים באפשרות View trace details.

    נפתחת חלונית Trace details ומוצג בה ה-Trace שנבחר.

מידע נוסף על השימוש ב-Logs Explorer מופיע במאמר הצגת יומנים באמצעות Logs Explorer.

צפייה ב-Collector וניפוי באגים שלו

הכלי Google-Built OpenTelemetry Collector מספק באופן אוטומטי מדדים של יכולת התבוננות עצמית כדי לעזור לכם לעקוב אחרי הביצועים שלו ולוודא שצינור ההזנה של OTLP ממשיך לפעול.

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

כדי להתקין את מרכז הבקרה:

  1. במסוף Google Cloud , עוברים לדף  Dashboards:

    עוברים אל מרכזי בקרה.

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

  2. לוחצים על תבניות של לוחות בקרה.
  3. מחפשים את מרכז הבקרה OpenTelemetry Collector.
  4. אופציונלי: כדי לראות תצוגה מקדימה של לוח הבקרה, בוחרים אותו.
  5. לוחצים על הוספת מרכז הבקרה לרשימה ומשלימים את תיבת הדו-שיח.

    בתיבת הדו-שיח אפשר לבחור את השם של לוח הבקרה ולהוסיף לו תוויות.

מידע נוסף על התקנת לוחות בקרה זמין במאמר התקנה של תבנית לוח בקרה.