מעקב אחר הביצועים באמצעות עקבות בצד הלקוח

כדי לעקוב אחרי בקשות של Firestore במצב Datastore (Datastore) ולנפות בהן באגים מקצה לקצה, אפשר להפעיל מעקבים בספריית הלקוח של Java. מעקב בצד הלקוח יכול לספק אות לגבי הביצועים כפי שהם נחווים באפליקציה שלכם, וגם תובנות שיכולות לעזור בניפוי באגים בבעיות.

עקבות בצד הלקוח, שנאספות על ידי הפעלת RPC מהלקוח, מספקות את המידע הבא:

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

OpenTelemetry

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

ייצוא של עקבות באמצעות רכיבי ייצוא ורכיבי איסוף

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

בנוסף לכלי לייצוא נתונים, מומלץ להגדיר Collector של OpenTelemetry. ה-Collector מאפשר לשירות להעביר נתונים במהירות, והוא מטפל בפעולות נוספות כמו ניסיונות חוזרים, אריזה והצפנה. הכלי Collector פועל לצד האפליקציה. ה-Collector מקבל הודעות של פרוטוקול OpenTelemetry ‏ (OTLP), מעבד את ההודעות ומייצא אותן אל קצה העורף של מערכת הניטור.

מגבלות

טווחים של עקבות זמינים רק בספריית הלקוח של Java.

חיוב

בנוסף לשימוש ב-Datastore, יכול להיות שתחויבו על מעקב בצד הלקוח.

אין חיובים על איסוף עקבות או על שימוש במסגרת OpenTelemetry.

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

כדי להבין טוב יותר את החיוב, מומלץ להתחיל עם יחס דגימה קטן של מעקב (מעקב אחרי אחוז קטן מה-RPC) על סמך התנועה שלכם.

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

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

  • חשוב לוודא שהגדרתם את חשבון השירות שדרכו האפליקציה כותבת עקבות לשרת הקצה העורפי של כלי התצפית עם התפקידים הנדרשים בניהול הזהויות והרשאות הגישה:

    פעולת מעקב תפקיד IAM
    קריאה של נתוני המעקב roles/cloudtrace.user
    כתיבת נתוני עקבות roles/cloudtrace.agent
    קריאה/כתיבה של עקבות roles/cloudtrace.admin

  • מוודאים ש-Trace API מופעל בפרויקט הזה.

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

בקטע הזה מוצגות הגדרות לדוגמה של מעקב בצד הלקוח. אפשר לייצא ל-Collector או ישירות ל-backend של יכולת התבוננות. יש גם את האפשרויות הבאות להגדרת מעקב בצד הלקוח:

ייצוא מעקבים אל Collector באמצעות OpenTelemetry APIs

הקוד הבא מגדיר את ספריית הלקוח של Java ל-Datastore לייצא טווחים עם יחס דגימה של 10% אל OpenTelemetry Collector.

Java

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
  OtlpGrpcSpanExporter
  .builder()
  .setEndpoint("http://localhost:4317") // Replace with your OTLP endpoint
  .build();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
  BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

ייצוא ישירות אל קצה עורפי של ניראות באמצעות ממשקי OpenTelemetry API

הקוד הבא מגדיר את ספריית הלקוח של Java לייצוא ישיר של טווחים של מעקב ל-Cloud Trace עם יחס דגימה של 10%. אתם יכולים להשתמש בייצואנים של ספקי שירותי נראות אחרים כדי לייצא ישירות אל הקצה העורפי שלהם. אם הקצה העורפי של הניראות (observability) תומך בהטמעה של OTLP, אפשר להשתמש ב-OpenTelemetry OtlpGrpcSpanExporter כדי לייצא לקצה העורפי במקום להשתמש בכלי ייצוא בהתאמה אישית.

Java

// TraceExporter needed for this use case
import com.google.cloud.opentelemetry.trace.TraceExporter;

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());
SpanExporter gcpTraceExporter = TraceExporter.createWithDefaultConfiguration();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
SpanProcessor gcpBatchSpanProcessor =
  BatchSpanProcessor.builder(gcpTraceExporter).build();

// Export directly to Cloud Trace with 10% trace sampling ratio
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

ייצוא למרכז מידע עם סוכנים אוטומטיים

מריצים את OpenTelemetry Collector עם רכיבי OTLP gRPC receivers מופעלים. מגדירים את כלי הייצוא של הנציג ל-otlp ומציינים את נקודת הקצה שאליה הנציג צריך לייצא את הנתונים. בדוגמה הבאה נעשה שימוש ביחס דגימה של 10% והנתונים נשלחים אל Collector שמקשיב ביציאה 4317 של localhost.

טרמינל

DATASTORE_ENABLE_TRACING=ON                            \
java                                                   \
-javaagent:path/to/opentelemetry-javaagent.jar         \
-Dotel.traces.exporter=otlp                            \
-Dotel.exporter.otlp.endpoint="http://localhost:4317"  \
-Dotel.traces.sampler=traceidratio                     \
-Dotel.traces.sampler.arg=0.1                          \
-Dotel.service.name="My App"                           \
-jar myapp.jar

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

בנוסף להגדרת משתנה הסביבה DATASTORE_ENABLE_TRACING=ON, צריך להוסיף את תוסף הסוכן של OpenTelemetry Java עבור הקצה העורפי הספציפי שלכם. בדוגמה הבאה נעשה שימוש בתוסף Trace exporter ובשיעור דגימה של 10% למעקב.

טרמינל

DATASTORE_ENABLE_TRACING=ON                                                \
java                                                                       \
-javaagent:path/to/opentelemetry-javaagent.jar                             \
-Dotel.javaagent.extensions=/path/to/exporter-auto-0.26.0-alpha-shaded.jar \
-Dotel.traces.exporter=google_cloud_trace                                  \
-Dotel.traces.sampler=traceidratio                                         \
-Dotel.traces.sampler.arg=0.1                                              \
-Dotel.service.name="My Application"                                       \
-jar myapp.jar

דוגמה למעקב

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

דוגמה לטווח של מעקב

טווח מעקב שנצפה מ-Cloud Trace.

דוגמה ליומן אירועים

יומן אירועים של יחידה לוגית למעקב שנצפה מ-Cloud Trace.

ערכים לדוגמה של מאפיינים

ערכי מאפיינים של יחידה לוגית למעקב שמוצגת ב-Cloud Trace.

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