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

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

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

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

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

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

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

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

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

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

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

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

כדי ליצור יחידה לוגית למעקב:

1. עליך לבצע שינויים באפליקציה כדי לקבל Tracer של OpenTelemetry. ב-OpenTelemetry, כלי למעקב הוא יוצר של טווחים. אפשר להשיג אובייקט 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 יוצרת טווח בכל פעם שקוראים לה:

   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