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

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

תצוגה מקדימה

השימוש בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאי שירות הכלליים" בתנאים הספציפיים של השירות. השימוש בתכונות בגרסת טרום-GA הוא "כפי שהן" (As is), ויכול להיות שהתמיכה בהן תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.

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

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

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

OpenTelemetry

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

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

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

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

מגבלות

יש כמה מגבלות לטראסים בצד הלקוח:

• אפשר להשתמש בטווחים של Trace בספריות הלקוח של Java ו-Node.js.
• ספריית הלקוח לא יוצרת טווחי מעקב עבור מאזינים בזמן אמת.

חיוב

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

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

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

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

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

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

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

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

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

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

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

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

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

הקוד הבא מגדיר את ספריית הלקוח כך שתייצא טווחים עם יחס דגימה של 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 also use other `BatchSpanProcessorBuilder` methods
// 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();

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

    

Node.js (אדמין)

import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';

import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";
import pkg3 from "@opentelemetry/exporter-trace-otlp-grpc";

const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;
const { OTLPTraceExporter } =  pkg3;

const provider = new NodeTracerProvider(
  // Provide your chosen NodeTracerConfig such as sampler and span limit
  {
    sampler: new TraceIdRatioBasedSampler(0.1),
  }
);
provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
provider.register();

// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
  instrumentations: [
    new GrpcInstrumentation(
      // (optional): you can add GrpcInstrumentationConfig here
    ),
  ],
});


const settings: Settings = {
  projectId: 'my-project-id',
  preferRest: false,
  openTelemetry: {
    tracerProvider: trace.getTracerProvider()
  }
};

// Initialize Firestore
const firestore = new Firestore(settings);
// Add app code here

// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
  await provider
        .shutdown()
        .catch(error => console.error('Error terminating NodeTracerProvider:', error));
});
    

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

אם ספק שירותי ה-Observability שלכם תומך בהטמעה של OTLP, אתם יכולים להשתמש ב-OpenTelemetry exporter שלו כדי לייצא עקבות ישירות אל ה-Backend שלו. הקוד הבא מגדיר את ספריית הלקוח לייצוא ישיר של טווחי מעקב ל-Cloud Trace עם יחס דגימה של 10%.

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 also use other `BatchSpanProcessorBuilder` methods
// 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();

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

    

Node.js (אדמין)

import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';
import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";

import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";

const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;

const provider = new NodeTracerProvider(
  // Provide your chosen NodeTracerConfig such as sampler and span limits
  {
    sampler: new TraceIdRatioBasedSampler(0.1),
  }
);
provider.addSpanProcessor(new BatchSpanProcessor(new TraceExporter()));
provider.register();

// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
  instrumentations: [
    new GrpcInstrumentation(
      // (optional): you can add GrpcInstrumentationConfig here
    ),
  ],
});


const settings: Settings = {
  projectId: 'my-project-id',
  preferRest: false,
  openTelemetry: {
    tracerProvider: trace.getTracerProvider()
  }
};

// Initialize Firestore
const firestore = new Firestore(settings);
// ...

// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
  await provider
        .shutdown()
        .catch(error => console.error('Error terminating NodeTracerProvider:', error));
});
    

הטמעה ללא קוד

כדי להגדיר עקבות בלי לשנות את הקוד, פועלים לפי ההוראות הבאות:

Java (אדמין)

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

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

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

FIRESTORE_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

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

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

FIRESTORE_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                                              \

    

Node.js (אדמין)

כדי להגדיר שדרוג מידע ללא קוד, פועלים לפי ההוראות של OpenTelemetry לשדרוג מידע ב-JavaScript. קטע הקוד הבא מאפשר שדרוג מידע ושליחת מעקבים אל OpenTelemetry Collector:

npm install @opentelemetry/api
npm install @opentelemetry/auto-instrumentations-node


env \
FIRESTORE_ENABLE_TRACING=ON \
OTEL_TRACES_EXPORTER=otlp \
OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,grpc" \
OTEL_NODE_RESOURCE_DETECTORS="none" \
node --require @opentelemetry/auto-instrumentations-node/register my_app.js

    

דוגמה למעקב

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

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

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

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

דוגמה למעקב אחר מחסנית (Stack Trace) ולאירוע חריג

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

• עיון בהפניה למאפיינים ולאירועים של טווח מעקב
• מידע נוסף על מעקב בצד השרת