Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

דוגמה של מכשור Java

במאמר הזה נסביר איך להטמיע אפליקציית Java כדי לאסוף נתוני מעקב ומדדים באמצעות OpenTelemetry SDK ו-OpenTelemetry Collector. הוא גם מסביר איך לכתוב יומנים מובנים בפורמט JSON לפלט רגיל. כדי להתנסות בהטמעה, מורידים ומריצים את האפליקציה לדוגמה. האפליקציה הזו משתמשת ב-Spring Boot Framework ומפיקה נתוני יומן, מדדים ונתוני מעקב.

כשמשתמשים ב-OpenTelemetry collector, מוסיפים אינסטרומנטציה לאפליקציה באמצעות ה-SDK וה-OTLP in-process exporter של ה-SDK. הכלי הזה לא תלוי בספק. אתם גם פורסים OpenTelemetry Collector שמקבל טלמטריה מהכלי לייצוא נתונים בתהליך, ואז מייצא את הטלמטריה הזו לפרויקט Google Cloud . מידע נוסף על קולקטורים זמין במאמר בנושא Google-Built OpenTelemetry Collector.

מומלץ להשתמש ב-OpenTelemetry collector כדי לייצא את נתוני הטלמטריה אם הסביבה שלכם תומכת בשימוש ב-collector. בסביבות מסוימות, צריך להשתמש בכלי לייצוא שפועל בתהליך ושולח נתונים ישירות לGoogle Cloud פרויקט. מידע על הטמעה בתהליך זמין במאמר מעבר מ-Trace exporter לנקודת הקצה OTLP.

למידע נוסף על מכשור, אפשר לעיין במסמכים הבאים:

מידע על הטמעה ידנית והטמעה ללא קוד

האינסטרומנטציה שמתוארת במסמך הזה מסתמכת על OpenTelemetry zero-code instrumentation כדי לשלוח טלמטריה לפרויקט Google Cloud שלכם. ב-Java, ‏ zero-code instrumentation מתייחס לשיטה של החדרת קוד בייט באופן דינמי לספריות ולמסגרות כדי לתעד טלמטריה. הוספת כלי מעקב ללא קוד יכולה לאסוף נתוני טלמטריה לגבי דברים כמו קריאות HTTP לדואר נכנס ויוצא. מידע נוסף זמין במאמר בנושא Java Agent.

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

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

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

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

יוצרים Google Cloud פרויקט:
```
gcloud projects create PROJECT_ID
```
מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.
בוחרים את הפרויקט שיצרתם: Google Cloud
```
gcloud config set project PROJECT_ID
```
מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

מפעילים את ממשקי ה-API של Cloud Logging,‏ Cloud Monitoring,‏ Cloud Trace וטלמטריה:

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

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

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

התקינו את ה-CLI של Google Cloud.

אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה:

gcloud init

יוצרים או בוחרים Google Cloud פרויקט.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

יוצרים Google Cloud פרויקט:
```
gcloud projects create PROJECT_ID
```
מחליפים את PROJECT_ID בשם של פרויקט Google Cloud שיוצרים.
בוחרים את הפרויקט שיצרתם: Google Cloud
```
gcloud config set project PROJECT_ID
```
מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

מפעילים את ממשקי ה-API של Cloud Logging,‏ Cloud Monitoring,‏ Cloud Trace וטלמטריה:

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

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

כדי לקבל את ההרשאות שדרושות לאפליקציית הדוגמה כדי לכתוב נתונים של יומנים, מדדים ומעקב, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- Logs Writer (roles/logging.logWriter)
- כתיבת מדדי מעקב (roles/monitoring.metricWriter)
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
ההרשאות האלה מספיקות אם מריצים את הדוגמה ב-Cloud Shell, במשאבים או בסביבת פיתוח מקומית. Google Cloud

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

כדי לקבל את ההרשאות שדרושות להצגת נתוני היומן, המדדים והמעקב, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים בפרויקט:
- כלי הצפייה ביומנים (roles/logging.viewer)
- צפייה ב-Monitoring (roles/monitoring.viewer)
- משתמש Cloud Trace (roles/cloudtrace.user)
להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

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

הגדרת האפליקציה לשימוש ב-OpenTelemetry Java Agent
הגדרה של OpenTelemetry
הגדרת רישום ביומן במבנה
כתיבת יומנים מובְנים

הגדרת האפליקציה לשימוש ב-OpenTelemetry Java Agent

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

בדוגמת הקוד הבאה מוצג Dockerfile שמוריד את קובץ ה-JAR של OpenTelemetry Java Agent ומעדכן את ההפעלה של שורת הפקודה כדי להעביר את הדגל -javaagent.

כדי לראות את הדוגמה המלאה, בסרגל הכלים של הדוגמה, לוחצים על הלוגו של GitHub.

RUN wget -O /opentelemetry-javaagent.jar https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.31.0/opentelemetry-javaagent.jar
CMD sh -c "java -javaagent:/opentelemetry-javaagent.jar -cp app:app/lib/* com.example.demo.DemoApplication \
	2>&1 | tee /var/log/app.log"

אפשרות נוספת היא להגדיר את הדגל -javaagent במשתנה הסביבה JAVA_TOOL_OPTIONS:

export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar"

הגדרת OpenTelemetry

הגדרת ברירת המחדל של OpenTelemetry Java Agent מייצאת עקבות ומדדים באמצעות פרוטוקול OTLP. בנוסף, המדיניות מגדירה את OpenTelemetry לשימוש בפורמט W3C Trace Context כדי להפיץ את הקשר של נתוני המעקב. ההגדרה הזו מבטיחה שלטווחים יהיו יחסי הורה-צאצא נכונים בתוך מעקב.

למידע נוסף על אפשרויות ההגדרה, אפשר לעיין במאמר בנושא OpenTelemetry Java automatic instrumentation.

הגדרת רישום ביומן במבנה

כדי לכלול את פרטי העקבות כחלק מהיומנים בפורמט JSON שנכתבים לפלט רגיל, צריך להגדיר את האפליקציה כך שתפיק יומנים מובְנים בפורמט JSON. מומלץ להשתמש ב-Log4j2 כהטמעה של רישום ביומן. בדוגמת הקוד הבאה מוצג קובץ log4j2.xml שהוגדר להפקת יומנים מובנים בפורמט JSON באמצעות פריסת תבנית JSON:

<!-- Format JSON logs for the Cloud Logging agent
https://cloud.google.com/logging/docs/structured-logging#special-payload-fields -->

<!-- Log4j2's JsonTemplateLayout includes a template for Cloud Logging's special JSON fields
https://logging.apache.org/log4j/2.x/manual/json-template-layout.html#event-templates -->
<JsonTemplateLayout eventTemplateUri="classpath:GcpLayout.json">
  <!-- Extend the included GcpLayout to include the trace and span IDs from Mapped
  Diagnostic Context (MDC) so that Cloud Logging can correlate Logs and Spans

  Since log4j2 2.24.0, GcpLayout.json already includes trace context logging from MDC and
  the below additional fields are no longer needed -->
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace"
    format="JSON"
    value='{"$resolver": "mdc", "key": "trace_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/spanId"
    format="JSON"
    value='{"$resolver": "mdc", "key": "span_id"}'
  />
  <EventTemplateAdditionalField
    key="logging.googleapis.com/trace_sampled"
    format="JSON"
    value="true"
  />
</JsonTemplateLayout>

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

‫logging.googleapis.com/trace: שם המשאב של ה-trace שמשויך לרשומה ביומן.
‫logging.googleapis.com/spanId: מזהה הטווח עם העקבות שמשויך לרשומה ביומן.
‫logging.googleapis.com/trace_sampled: הערך בשדה הזה חייב להיות true או false.

מידע נוסף על השדות האלה זמין במאמר בנושא LogEntry.

כתיבת יומנים מובנים

כדי לכתוב יומני רישום מובנים שמקושרים למעקב, משתמשים בממשק ה-API של רישום היומנים SLF4J. לדוגמה, ההצהרה הבאה מראה איך להפעיל את המתודה Logger.info():

logger.info("handle /multi request with subRequests={}", subRequests);

ה-OpenTelemetry Java Agent מאכלס באופן אוטומטי את Mapped Diagnostic Context של SLF4J עם הקשר של ה-span הפעיל הנוכחי בהקשר של OpenTelemetry. ההקשר הממופה של האבחון נכלל ביומני ה-JSON, כפי שמתואר במאמר בנושא הגדרת רישום ביומן עם מבנה.

הפעלת אפליקציה לדוגמה שהוגדרה לאיסוף טלמטריה

האינסטרומנטציה באפליקציית הדוגמה משתמשת בפורמטים ניטרליים לספקים, כמו JSON לנתוני יומן ו-OTLP לנתוני מדדים ולנתוני מעקב. האפליקציה משתמשת גם ב-Spring Boot Framework. ‫OpenTelemetry Collector שולח נתוני יומן ומדדים לפרויקט באמצעות כלי ייצוא של Google. הוא שולח את נתוני המעקב לפרויקט שלכם באמצעות Telemetry API, שמשתמש ב-OTLP.

לאפליקציה יש שתי נקודות קצה:

נקודת הקצה /multi מטופלת על ידי הפונקציה handleMulti. מחולל העומסים באפליקציה שולח בקשות לנקודת הקצה /multi. כשנקודת הקצה הזו מקבלת בקשה, היא שולחת שלוש עד שבע בקשות לנקודת הקצה /single בשרת המקומי.

/**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/multi")
public Mono<String> handleMulti() throws Exception {
  int subRequests = ThreadLocalRandom.current().nextInt(3, 8);

  // Write a structured log with the request context, which allows the log to
  // be linked with the trace for this request.
  logger.info("handle /multi request with subRequests={}", subRequests);

  // Make 3-7 http requests to the /single endpoint.
  return Flux.range(0, subRequests)
      .concatMap(
          i -> client.get().uri("http://localhost:8080/single").retrieve().bodyToMono(Void.class))
      .then(Mono.just("ok"));
}

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

/**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 *
 * <p>OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the controller body.
 */
@GetMapping("/single")
public String handleSingle() throws InterruptedException {
  int sleepMillis = ThreadLocalRandom.current().nextInt(100, 200);
  logger.info("Going to sleep for {}", sleepMillis);
  Thread.sleep(sleepMillis);
  logger.info("Finishing the request");
  return String.format("slept %s\n", sleepMillis);
}

הורדה ופריסה של האפליקציה

כדי להריץ את הדוגמה:

במסוף Google Cloud , מפעילים את Cloud Shell.

הפעלת Cloud Shell

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

משכפלים את המאגר:

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-java

עוברים לספריית הדוגמאות:

cd opentelemetry-operations-java/examples/instrumentation-quickstart

מפתחים ומריצים את הדוגמה:
```
docker compose up --abort-on-container-exit
```
אם אתם לא מריצים את האפליקציה ב-Cloud Shell, אתם צריכים להריץ אותה עם משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS שמצביע על קובץ פרטי הכניסה. ‫Application Default Credentials‏ (ADC) מספק קובץ פרטי כניסה בנתיב $HOME/.config/gcloud/application_default_credentials.json.
```
# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
```

הצגת המדדים

האינסטרומנטציה של OpenTelemetry באפליקציית הדוגמה יוצרת מדדים של Prometheus שאפשר לראות באמצעות Metrics Explorer:

Prometheus/http_server_duration_milliseconds/histogram מתעד את משך הזמן של בקשות לשרת ומאחסן את התוצאות בהיסטוגרמה.
Prometheus/http_client_duration_milliseconds/histogram מתעד את משך הזמן של בקשות הלקוח ומאחסן את התוצאות בהיסטוגרמה.

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

נכנסים לדף Metrics explorer במסוף Google Cloud :
כניסה אל Metrics Explorer

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שבה הכותרת המשנית היא Monitoring.
בסרגל הכלים של מסוף Google Cloud , בוחרים את Google Cloud הפרויקט. בהגדרות של מרכז האפליקציות, בוחרים את הפרויקט המארח של מרכז האפליקציות או את פרויקט הניהול של התיקייה לניהול אפליקציות.
ברכיב Metric, מרחיבים את התפריט Select a metric, כותבים http_server בשורת הסינון ומשתמשים בתפריטי המשנה כדי לבחור סוג ספציפי של משאב ומדד:
1. בתפריט Active resources בוחרים באפשרות Prometheus Target.
2. בתפריט Active metric categories בוחרים באפשרות Http.
3. בתפריט Active metrics בוחרים מדד.
4. לוחצים על אישור.
כדי להוסיף מסננים שמסירים סדרות זמן מתוצאות השאילתה, משתמשים ברכיב Filter.
מגדירים את אופן התצוגה של הנתונים.
כשמדובר במדדים מצטברים, הכלי 'Metrics Explorer' מבצע נורמליזציה אוטומטית של הנתונים שנמדדו לפי תקופת ההתאמה, וכתוצאה מכך מוצג בתרשים קצב. מידע נוסף זמין במאמר סוגים, סוגים והמרות.

כשמודדים ערכים מסוג integer או double, כמו שני המדדים counter, הכלי Metrics Explorer מסכם באופן אוטומטי את כל סדרות הזמנים. כדי לראות את הנתונים של נתיבי ה-HTTP‏ /multi ו-/single, מגדירים את התפריט הראשון של הרשומה Aggregation לערך None.

מידע נוסף על הגדרת תרשים זמין במאמר איך בוחרים מדדים כשמשתמשים ב-Metrics Explorer.

הצגת העקבות

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

כדי להציג את נתוני העקבות:

נכנסים לדף Trace explorer במסוף Google Cloud :
כניסה אל Trace explorer

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

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

בכרטיסייה מוצגים יומנים בודדים. כדי לראות את הפרטים של הרשומה ביומן, מרחיבים את הרשומה. אפשר גם ללחוץ על הצגת יומנים כדי לראות את היומן באמצעות Logs Explorer.

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

הצגת רישומי היומן

בכלי Logs Explorer אפשר לבדוק את היומנים, וגם לראות את העקבות המשויכים, אם הם קיימים.

במסוף Google Cloud , נכנסים לדף Logs Explorer:
כניסה אל Logs Explorer

אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Logging.
מאתרים יומן עם התיאור של handle /multi request.

כדי לראות את פרטי היומן, מרחיבים את הרשומה ביומן.
לוחצים על Traces (עקבות) ברשומה ביומן עם ההודעה handle /multi request (טיפול בבקשה מרובה), ואז בוחרים באפשרות View trace details (הצגת פרטי העקבות).

נפתחת חלונית Trace details ומוצג בה ה-Trace שנבחר.

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

מידע נוסף על השימוש ב-Logs Explorer מופיע במאמר הצגת יומנים באמצעות Logs Explorer.