הפעלה של אותות טלמטריה בספריות לקוח ב-Go

Cloud de Confiance by S3NS מספק מעקב, רישום ביומן ואבחון עוצמתיים לאפליקציות Go.

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

אותות זמינים

האותות כוללים את נתוני הטלמטריה הבאים, בהתאם למוסכמות הסמנטיות של OpenTelemetry:

• עקבות: עקבות ברמה נמוכה של HTTP/gRPC שמייצגים את בקשות הרשת שנוצרות על ידי ספריות הלקוח.
• מדדים: מדדים של בקשות לקוח, מעקב אחר זמן האחזור ושיעורי הבקשות. המדד הראשי הוא gcp.client.request.duration.
• יומנים: יומני שגיאות שניתן לפעול לפיהם ברמה DEBUG (ומעלה), שמספקים פרטים על בקשות שנכשלו בשכבת התעבורה, גם אם בסופו של דבר נעשה ניסיון חוזר להעביר אותן והן מצליחות.

האותות כוללים מאפיינים סטנדרטיים של OpenTelemetry (לדוגמה, http.response.status_code ו-rpc.system.name) ומאפיינים מותאמים אישית ספציפיים ל- Cloud de Confiance by S3NS, שעשויים לכלול את המאפיינים הבאים ומאפיינים דומים:

• ‫gcp.client.service: שם השירות (לדוגמה, pubsub או storage).
• ‫gcp.client.repo: מאגר ספריית הלקוח (לדוגמה, googleapis/google-cloud-go).
• ‫gcp.client.version: גרסת ספריית הלקוח.
• ‫gcp.client.artifact: הנתיב הספציפי של המודול (לדוגמה, cloud.google.com/go/secretmanager).
• ‫gcp.resource.destination.id: המזהה של המשאב שעליו מתבצעת הפעולה.
• gcp.errors.domain: דומיין השגיאה ליומני שגיאות שניתן לפעול לפיהם.
• ‫gcp.errors.metadata.<key>: מפתחות נוספים של מטא-נתונים של שגיאות לבקשות שנכשלו (שטוחים).

רשימה מלאה של מאפיינים סטנדרטיים זמינה במוסכמות סמנטיות של OpenTelemetry HTTP ו-gRPC.

הפעלת טלמטריה

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

ב-Go, משתמשים במשתני הסביבה הבאים כדי להפעיל עקבות, מדדים ויומנים באופן גלובלי בכל ספריות הלקוח של Cloud de Confiance by S3NS :

# Enable trace generation (span emission)
export GOOGLE_SDK_GO_TRACING=true

# Enable metrics
export GOOGLE_SDK_GO_METRICS=true

# Enable logging
export GOOGLE_SDK_GO_LOGGING=true

הפצת הקשר של מעקב

ספריות הלקוח של Go מעבירות באופן אוטומטי הקשרים פעילים של מעקב אל שירותיCloud de Confiance by S3NS , גם אם יצירת המעקב (GOOGLE_SDK_GO_TRACING) מושבתת.

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

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

ייצוא נתוני טלמטריה

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

מעקב ומדדים

כדי לייצא את העקבות והמדדים שנוצרו על ידי ספריות הלקוח של Go, צריך לאתחל את OpenTelemetry SDK עם כלי הייצוא המועדף (לדוגמה, OTLP) ולהגדיר את המפיץ הגלובלי של מפת הטקסט ב-main.go:

package main

import (
    "context"
    "log"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
    ctx := context.Background()

    // Initialize the exporter
    exporter, err := otlptracegrpc.New(ctx)
    if err != nil {
        log.Fatalf("failed to initialize exporter: %v", err)
    }

    // Set up the tracer provider
    tp := trace.NewTracerProvider(trace.WithBatcher(exporter))
    defer func() {
        // Ensure all spans are flushed before exit
        if err := tp.Shutdown(ctx); err != nil {
            log.Fatalf("failed to shutdown TracerProvider: %v", err)
        }
    }()

    otel.SetTracerProvider(tp)

    // Set up the global propagator
    otel.SetTextMapPropagator(propagation.TraceContext{})

    // ... initialize Cloud de Confiance by S3NS client libraries ...
}

לפרטים נוספים על קישור OpenTelemetry SDK ל-Cloud Monitoring או ל-Cloud Trace, אפשר לעיין במדריכים של Google Cloud Observability ל-Go.

רישום ביומן

ספריות הלקוח של Go משתמשות ברישום ביומן במבנה מוגדר באמצעות slog כדי להפיק שגיאות שניתן לפעול לפיהן ברמה DEBUG. היומנים המיוצאים כוללים באופן אוטומטי מזהי מעקב ומזהי טווח אם מסגרת הרישום שלכם מוגדרת לחילוץ שלהם מ-context.Context.

כדי לקבל את היומנים האלה, צריך לספק ללקוח *slog.Logger מוגדר עם ההפעלה (לדוגמה, באמצעות option.WithLogger()).

כדי להפנות את היומנים המובנים האלה ל-Cloud Logging, צריך להגדיר את slog כך שיכתוב JSON לפלט רגיל (stdout). אם אתם פורסים לסביבה כמו Google Kubernetes Engine או Cloud Run, הסוכנים המובנים יגרדו את היומנים האלה באופן אוטומטי.

package main

import (
    "context"
    "log/slog"
    "os"

    "cloud.google.com/go/secretmanager/apiv1"
    "google.golang.org/api/option"
)

func main() {
    ctx := context.Background()

    // Configure slog to output JSON to stdout at the DEBUG level
    opts := &slog.HandlerOptions{Level: slog.LevelDebug}
    logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))

    // Provide the logger to the client
    client, err := secretmanager.NewClient(ctx, option.WithLogger(logger))
    if err != nil {
        // handle error
    }
    defer client.Close()
}

הוראות נוספות למיפוי הקשרים של מעקב OpenTelemetry ועיצוב יומנים מובְנים בפורמט JSON בהתאם לשדות המטען הייעודי (payload) הצפויים של Cloud Logging מופיעות במאמר הגדרת רישום מובְנה ביומן עבור Go.