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

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

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

• אינסטרומנטציה וניראות.
• בחירת גישה לאינסטרומנטציה.

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

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

Enable the 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

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

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

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

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 יוצרת טווח בכל פעם שקוראים לה:

   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