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

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

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

• מכשור ויכולת צפייה.
• בחירת גישה להוספת מכשור.

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

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

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

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

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

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

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

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

כדי ליצור טווח:

1. עליך לבצע שינויים באפליקציה כדי לקבל Tracer של OpenTelemetry. ב-OpenTelemetry,‏ tracer הוא יוצר של span. אפשר להשיג אובייקט Tracer כמו בדוגמה הבאה:

   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
   )
   

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

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

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

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

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

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

   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 Histogram:

   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