כתיבת מדדי OTLP באמצעות OpenTelemetry Collector sidecar

במדריך הזה נסביר איך לכתוב, לפרוס ולקרוא לשירות Cloud Run שמדווח על מדדי OTLP מותאמים אישית אל Google Cloud Managed Service For Prometheus באמצעות Google-Built OpenTelemetry Collector כ-sidecar. מידע על כלי האיסוף שנוצר על ידי Google זמין במאמר סקירה כללית של כלי האיסוף OpenTelemetry שנוצר על ידי Google.

אם יש לכם שירות Cloud Run שמדווח על מדדי Prometheus, אתם צריכים להשתמש במקום זאת ב-Prometheus sidecar for Cloud Run.

מטרות

• כתיבה, פיתוח ופריסה של שירות ב-Cloud Run באמצעות Google-Built OpenTelemetry Collector כקובץ עזר.
• יצירת מדדים בהתאמה אישית ודיווח עליהם לשירות המנוהל של Google Cloud ל-Prometheus.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

• Cloud Build
• Artifact Registry
• Google Cloud Managed Service For Prometheus
• Cloud Run

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

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

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

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. מפעילים את ממשקי ה-API של Cloud Run,‏ Cloud Monitoring,‏ Artifact Registry ו-Cloud Build.

   תפקידים שנדרשים להפעלת ממשקי API

   כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

   הפעלת ממשקי ה-API

2. מתקינים ומפעילים את ה-CLI של gcloud.
3. מעדכנים את Google Cloud CLI: gcloud components update

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

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

• עריכה ב-Cloud Build (roles/cloudbuild.builds.editor)
• אדמין ב-Cloud Run (roles/run.admin)
• יצירת חשבונות שירות (roles/iam.serviceAccountCreator)
• אדמין IAM בפרויקט (roles/resourcemanager.projectIamAdmin)
• כתיבת מדדי מעקב (roles/monitoring.metricWriter)
• משתמש בחשבון שירות (roles/iam.serviceAccountUser)
• צרכן שימוש בשירות (roles/serviceusage.serviceUsageConsumer)
• אדמין באחסון (roles/storage.admin)

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

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

הערה: התפקידים הבסיסיים של IAM עשויים גם להכיל הרשאות להשלמת המדריך. לא מומלץ להקצות תפקידים בסיסיים בסביבת ייצור, אבל אפשר להקצות אותם בסביבת פיתוח או בדיקה.

חשוב גם לציין שלזהות השירות של Cloud Run צריך להיות מוקצה התפקיד Monitoring Metric Writer (roles/monitoring.metricWriter). יכול להיות שלחשבון השירות שמשמש כברירת מחדל של Compute Engine יש את התפקיד הזה כברירת מחדל, אבל יכול להיות שתצטרכו להוסיף אותו אם שיניתם את ההרשאות שלו או אם אתם משתמשים בחשבון שירות אחר.

הגדרת ברירות מחדל ב-gcloud

כדי להגדיר את gcloud עם ערכי ברירת מחדל לשירות Cloud Run:

1. מגדירים את פרויקט ברירת המחדל:

   gcloud config set project PROJECT_ID

   מחליפים את PROJECT_ID בשם הפרויקט שיצרתם לצורך המדריך הזה.

2. מגדירים את gcloud לאזור שבחרתם:

   gcloud config set run/region REGION

   מחליפים את REGION באזור נתמך ב-Cloud Run לבחירתכם.

מיקומים של Cloud Run

‫Cloud Run הוא שירות אזורי, כלומר התשתית שמריצה את שירותי Cloud Run ממוקמת באזור ספציפי ומנוהלת על ידי Google כך שתהיה זמינה באופן יתירתי בכל התחומים באותו אזור.

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

‫Cloud Run זמין באזורים הבאים:

בכפוף לתמחור ברמה 1

• asia-east1 (טייוואן)
• asia-northeast1 (טוקיו)
• ‫asia-northeast2 (אוסקה)
• asia-south1 (מומבאי, הודו)
• ‫asia-southeast3 (בנגקוק)
• europe-north1 (פינלנד) רמה נמוכה של CO₂
• europe-north2 (שטוקהולם) רמה נמוכה של CO₂
• europe-southwest1 (מדריד) רמה נמוכה של CO₂
• europe-west1 (בלגיה) רמה נמוכה של CO₂
• europe-west4 (הולנד) רמה נמוכה של CO₂
• europe-west8 (מילאנו)
• europe-west9 (פריז) רמה נמוכה של CO₂
• me-west1 (תל אביב)
• northamerica-south1 (מקסיקו)
• us-central1 (אייווה) רמה נמוכה של CO₂
• us-east1 (דרום קרוליינה)
• ‫us-east4 (צפון וירג'יניה)
• us-east5 (Columbus)
• us-south1 (דאלאס) רמה נמוכה של CO₂
• us-west1 (אורגון) רמה נמוכה של CO₂

בכפוף לתמחור ברמה 2

• africa-south1 (יוהנסבורג)
• asia-east2 (הונג קונג)
• asia-northeast3 (סיאול, קוריאה הדרומית)
• asia-southeast1 (סינגפור)
• asia-southeast2 (ג'אקארטה)
• asia-south2 (דלהי, הודו)
• ‫australia-southeast1 (סידני)
• australia-southeast2 (מלבורן)
• europe-central2 (ורשה, פולין)
• ‫europe-west10 (Berlin)
• europe-west12 (טורינו)
• europe-west2 (לונדון, בריטניה) רמה נמוכה של CO₂
• ‫europe-west3 (פרנקפורט, גרמניה)
• europe-west6 (ציריך, שווייץ) רמה נמוכה של CO₂
• ‫me-central1 (דוחה)
• ‫me-central2 (דמאם)
• northamerica-northeast1 (מונטריאול) רמה נמוכה של CO₂
• northamerica-northeast2 (טורונטו) רמה נמוכה של CO₂
• southamerica-east1 (סאו פאולו, ברזיל) רמה נמוכה של CO₂
• southamerica-west1 (סנטיאגו, צ'ילה) רמה נמוכה של CO₂
• ‫us-west2 (לוס אנג'לס)
• ‫us-west3 (סולט לייק סיטי)
• ‫us-west4 (לאס וגאס)

אם כבר יצרתם שירות Cloud Run, תוכלו לראות את האזור בלוח הבקרה של Cloud Run בGoogle Cloud מסוף.

אישור

יצירת מאגר תמונות ב-Artifact Registry

יוצרים מאגר Docker ב-Artifact Registry לאירוח קובץ האימג' של שירות לדוגמה:

gcloud artifacts repositories create run-otel \
    --repository-format=docker \
    --location=REGION \
    --project=PROJECT_ID

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID בשם הפרויקט שיצרתם לצורך המדריך הזה.
• ‫REGION REGION עם אזור Cloud Run נתמך לפי בחירתכם.

אחזור של דוגמת הקוד

כדי לאחזר את דוגמת קוד לשימוש:

1. משכפלים את מאגר האפליקציה לדוגמה ומעבירים אותו למכונה המקומית:

   המשך

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   אפשרות נוספת היא להוריד את הדוגמה כקובץ ZIP ולחלץ אותה.

2. עוברים לספרייה שמכילה את הקוד לדוגמה של Cloud Run:

   המשך

   cd golang-samples/run/custom-metrics/

בדיקת הקוד

הקוד במדריך הזה כולל את הרכיבים הבאים:

• שרת שמטפל בבקשות נכנסות ויוצר מדד בשם sidecar_sample_counter_total.

package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"

	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
	"go.opentelemetry.io/otel/metric"
	sdkmetric "go.opentelemetry.io/otel/sdk/metric"
	"go.opentelemetry.io/otel/sdk/resource"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

var counter metric.Int64Counter

func main() {
	ctx := context.Background()
	shutdown := setupCounter(ctx)
	defer shutdown(ctx)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	http.HandleFunc("/", handler)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	counter.Add(context.Background(), 100)
	fmt.Fprintln(w, "Incremented sidecar_sample_counter_total metric!")
}

func setupCounter(ctx context.Context) func(context.Context) error {
	serviceName := os.Getenv("K_SERVICE")
	if serviceName == "" {
		serviceName = "sample-cloud-run-app"
	}
	r, err := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			resource.Default().SchemaURL(),
			semconv.ServiceName(serviceName),
		),
	)
	if err != nil {
		log.Fatalf("Error creating resource: %v", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := sdkmetric.NewMeterProvider(
		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
		sdkmetric.WithResource(r),
	)

	meter := provider.Meter("example.com/metrics")
	counter, err = meter.Int64Counter("sidecar-sample-counter")
	if err != nil {
		log.Fatalf("Error creating counter: %s", err)
	}
	return provider.Shutdown
}

• ‫Dockerfile שמגדיר את סביבת ההפעלה של השירות.

FROM golang:1.25 as builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o sample-app

FROM alpine:3
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/sample-app /sample-app
CMD ["/sample-app"]

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

• קובץ הגדרות (config) בשביל הכלי לאיסוף נתונים.

  receivers:
    otlp:
      protocols:
        grpc:
        http:
  
  processors:
    batch:
      # batch metrics before sending to reduce API usage
      send_batch_max_size: 200
      send_batch_size: 200
      timeout: 5s
  
    memory_limiter:
      # drop metrics if memory usage gets too high
      check_interval: 1s
      limit_percentage: 65
      spike_limit_percentage: 20
  
    # automatically detect Cloud Run resource metadata                                                                                                                                               
    resourcedetection:
      detectors: [env, gcp]
      timeout: 2s
      override: false
  
    resource:
      attributes:
      # add instance_id as a resource attribute
      - key: service.instance.id
        from_attribute: faas.id
        action: upsert
        # parse service name from K_SERVICE Cloud Run variable                                                                                                                                       
      - key: service.name
        value: ${env:K_SERVICE}
        action: insert
  
  exporters:
    googlemanagedprometheus: # Note: this is intentionally left blank   
  
  extensions:
    health_check:
      endpoint: 0.0.0.0:13133
  service:
    extensions: [health_check]
    pipelines:
      metrics:
        receivers: [otlp]
        processors: [batch, memory_limiter, resourcedetection, resource]
        exporters: [googlemanagedprometheus]

• ‫Dockerfile שמאגד את ההגדרה שסופקה לתמונה של Collector במעלה הזרם.

  FROM us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.121.0
  
  COPY collector-config.yaml /etc/otelcol-google/config.yaml

שליחת הקוד

תהליך שליחת הקוד כולל שלושה שלבים: יצירת קובץ אימג' של קונטיינר באמצעות Cloud Build, העלאת קובץ האימג' של הקונטיינר ל-Artifact Registry ופריסת קובץ האימג' של הקונטיינר ל-Cloud Run.

כדי לשלוח את הקוד:

1. מפתחים את קובץ האימג' של שירות לדוגמה ומפרסמים אותו ב-Artifact Registry:

   gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app

   בסיום מוצלח, אמורה להופיע הודעת SUCCESS (הצלחה) עם המזהה, זמן היצירה ושם התמונה. התמונה מאוחסנת ב-Artifact Registry ואפשר לעשות בה שימוש חוזר אם רוצים.

2. מפתחים גרסת build של מאגר התגים של Collector ומפרסמים אותה ב-Artifact Registry:

   gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics

   בסיום מוצלח, אמורה להופיע הודעת SUCCESS (הצלחה) עם המזהה, זמן היצירה ושם התמונה. התמונה מאוחסנת ב-Artifact Registry ואפשר לעשות בה שימוש חוזר אם רוצים.

3. פורסים את האפליקציה:

   YAML

   1. יוצרים קובץ חדש בשם service.yaml עם התוכן הבא:

      apiVersion: serving.knative.dev/v1
      kind: Service
      metadata:
        name: SERVICE-NAME
        annotations:
          run.googleapis.com/launch-stage: BETA
      spec:
        template:
          metadata:
            annotations:
              run.googleapis.com/container-dependencies: "{app:[collector]}"
          spec:
            containers:
            - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
              name: app
              ports:
              - containerPort: CONTAINER_PORT
              env:
              - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
                value: "http://localhost:4317"
            - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
              name: collector
              startupProbe:
                httpGet:
                  path: /
                  port: 13133
      

   2. מחליפים את מה שכתוב בשדות הבאים:
      • ‫CONTAINER_PORT ביציאה שבה קונטיינר הכניסה של השירות מאזין. כברירת מחדל, הערך הוא 8080.
      • ‫SERVICE-NAME בשם של השירות, למשל custom-metrics-sample-service.

4. יוצרים את השירות החדש באמצעות הפקודה הבאה:

   gcloud run services replace service.yaml

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

אני רוצה לנסות

משתמשים בכתובת ה-URL מהפקודה gcloud run שמופיעה בקטע שליחת הקוד כדי להתחבר לשירות וליצור מדדים לדוגמה (אפשר להריץ את הפקודה הזו כמה פעמים כדי ליצור נתונים מעניינים יותר):

curl -H \
"Authorization: Bearer $(gcloud auth print-identity-token)" \
SERVICE_URL

מחליפים את SERVICE_URL בכתובת ה-URL של השירות.

לאחר מכן עוברים אל Metrics Explorer בקטע Cloud Monitoring במסוף Google Cloud ובוחרים במדד sidecar_sample_counter_total.

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

sidecar_sample_counter_total{instance="INSTANCE_ID"}

מחליפים את INSTANCE_ID במזהה של מופע כלשהו בשירות (אפשר למצוא אותו ביומני המופעים או בשרת המטא-נתונים).

השאילתה הזו יוצרת תרשים כמו זה שבהמשך:

הצלחה: פרסתם שירות Cloud Run שמדווח על מדדי OTLP מותאמים אישית לשירות המנוהל של Google Cloud ל-Prometheus.

הסרת המשאבים

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

מחיקת הפרויקט

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

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך.

כדי למחוק את הפרויקט:

זהירות: כשמוחקים פרויקט:

• התוכן של הפרויקט נמחק כולו. אם השתמשתם בפרויקט קיים כדי לתרגל את המשימות במדריך הזה, כשתמחקו אותו תימחק גם כל העבודה שביצעתם באותו פרויקט.
• מאבדים את מזהה הפרויקט בהתאמה אישית. כשיצרתם את הפרויקט, יכולתם לבחור לו מזהה פרויקט בהתאמה אישית כדי להשתמש בו בעתיד. כדי לשמור על כתובות ה-URL שמשתמשות במזהה הפרויקט, כמו appspot.com, צריך למחוק את המשאבים שנבחרו בפרויקט אבל לא את הפרויקט כולו.

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

1. במסוף Google Cloud , נכנסים לדף Manage resources.

   כניסה לדף Manage resources

2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

מחיקת משאבי הדרכה

1. מוחקים את שירות Cloud Run שפרסתם במדריך הזה. שירותי Cloud Run לא צוברים עלויות עד שהם מקבלים בקשות.

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

   gcloud run services delete SERVICE-NAME

   מחליפים את SERVICE-NAME בשם השירות.

   אפשר גם למחוק שירותים של Cloud Run מGoogle Cloud המסוף.

2. מסירים את הגדרת ברירת המחדל של האזור gcloud שהוספתם במהלך ההגדרה של המדריך:

    gcloud config unset run/region
   

3. מסירים את הגדרות הפרויקט:

    gcloud config unset project
   

4. מחיקת משאבים אחרים Google Cloud שנוצרו במדריך הזה:

   • מחיקת מאגר Docker ב-Artifact Registry

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

דוגמאות נוספות, כולל דוגמאות למעקב וליומנים, זמינות ב-GitHub.