הוספת מדדים ועקבות מותאמים אישית לאפליקציה

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

הדוגמאות במסמך הזה מבוססות על האפליקציה לדוגמה ב-Go שמתוארת במאמר דוגמה להוספה של כלי מדידה ב-Go, שזמינה ב-GitHub.

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

מפעילים את Cloud Logging API,‏ Cloud Monitoring API ו-Cloud Trace API, אם הם עדיין לא מופעלים.

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

כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

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

יצירת מעקבים בהתאמה אישית

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

כדי ליצור span:

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

   const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"
   
   var (
   	meter                = otel.Meter(scopeName)
   	tracer               = otel.Tracer(scopeName)
   	sleepHistogram       metric.Float64Histogram
   	subRequestsHistogram metric.Int64Histogram
   )
   

   שם המעקב, שמיוצג על ידי scopeName, מזהה את היקף המדידה של המעקבים שנוצרו.

2. משתמשים במכונה tracer כדי ליצור טווחים. בדוגמת הקוד הבאה, הפונקציה computeSubrequests יוצרת span בכל פעם שהיא נקראת:

   func computeSubrequests(r *http.Request, subRequests int) error {
   	// Add custom span representing the work done for the subrequests
   	ctx, span := tracer.Start(r.Context(), "subrequests")
   	defer span.End()
   
   	// Make specified number of http requests to the /single endpoint.
   	for i := 0; i < subRequests; i++ {
   		if err := callSingle(ctx); err != nil {
   			return err
   		}
   	}
   	// record number of sub-requests made
   	subRequestsHistogram.Record(ctx, int64(subRequests))
   	return nil
   }
   

   בדוגמת הקוד הקודמת, ה-span שנוצר מהפונקציה computeSubrequests מייצג את העבודה שבוצעה על ידי הפונקציה כולה. הסיבה לכך היא שהשלב הראשון של הפונקציה הוא להתחיל span חדש באמצעות tracer.Start, ומילת המפתח defer לפני span.End() מבטיחה שה-span יסתיים ממש לפני היציאה מהפונקציה.

   הערה: צריך לקרוא ל-End() כדי להשלים את הטווח. ‫OpenTelemetry מייצא רק טווחי זמן שהושלמו.

יצירת מדדים מותאמים אישית

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

כדי ליצור מדדים:

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

   const scopeName = "github.com/GoogleCloudPlatform/golang-samples/opentelemetry/instrumentation/app/work"
   
   var (
   	meter                = otel.Meter(scopeName)
   	tracer               = otel.Tracer(scopeName)
   	sleepHistogram       metric.Float64Histogram
   	subRequestsHistogram metric.Int64Histogram
   )
   

   שם המונה, שמיוצג על ידי scopeName, מזהה את היקף המדידה של המדדים שנוצרו.

2. משתמשים במכונה meter כדי ליצור כלים שיכולים לתעד מדדים. לדוגמה, הקוד הבא משתמש ב-meter כדי ליצור היסטוגרמה של OpenTelemetry:

   sleepHistogram, err = meter.Float64Histogram("example.sleep.duration",
   	metric.WithDescription("Sample histogram to measure time spent in sleeping"),
   	metric.WithExplicitBucketBoundaries(0.05, 0.075, 0.1, 0.125, 0.150, 0.2),
   	metric.WithUnit("s"))
   if err != nil {
   	panic(err)
   }

   הקוד הקודם יוצר היסטוגרמה בשם sleepHistogram.

3. משתמשים במופע של sleepHistogram כדי לתעד את זמן השינה, שנקבע כשמפעילים את הפונקציה randomSleep:

   func randomSleep(r *http.Request) time.Duration {
   	// simulate the work by sleeping 100 to 200 ms
   	sleepTime := time.Duration(100+rand.Intn(100)) * time.Millisecond
   	time.Sleep(sleepTime)
   
   	hostValue := attribute.String("host.value", r.Host)
   	// custom histogram metric to record time slept in seconds
   	sleepHistogram.Record(r.Context(), sleepTime.Seconds(), metric.WithAttributes(hostValue))
   	return sleepTime
   }
   

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

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

• התאמה בין מדדים למעקבים באמצעות דוגמאות
• OpenTelemetry
• OpenTelemetry Instrumentation
• מודל הנתונים של מדדי OpenTelemetry