‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

הפעלת מעקב מבוזר

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

מבוא

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

כלי המעקב ב-Apigee Edge וכלי הניפוי באגים ב-Apigee שימושיים לפתרון בעיות ולמעקב אחרי שרתי proxy של API. עם זאת, הכלים האלה לא שולחים נתונים לשרתי מעקב מבוזרים כמו Cloud Trace,‏ Jaeger או OpenTelemetry Collector.

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

בדוחות של מעקב מבוזר אפשר לראות את המידע הבא:

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

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

שלב	נקודת קצה (endpoint)	Flow
בקשה	בשם אחרים	Preflow
	בשם אחרים	PostFlow
	יעד	Preflow
	יעד	PostFlow
תשובה	בשם אחרים	Preflow
	בשם אחרים	PostFlow
	יעד	Preflow
	יעד	PostFlow

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

משתני מעקב שמוגדרים כברירת מחדל בדוח המעקב

חל על: ההגדרות של OpenTelemetry ושל OpenCensus.

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

‫RESP_SENT: הטווח הזה מתווסף אחרי קבלת תגובה משרת היעד. הוא כולל את מאפייני הצד של היעד שמפורטים בקטע משתנים בטווח RESP_SENT.
‫PROXY_POST_RESP_SENT: הטווח הזה מתווסף אחרי שתגובת ה-proxy נשלחת ללקוח. הוא מכיל את המאפיינים בצד ה-proxy שמפורטים בקטע Variables in the PROXY_POST_RESP_SENT span.
‫EVENT_FLOW_RESP ו-EVENT_FLOW_END: טווחי הזמן האלה מתווספים לשרתי proxy של API שמטפלים בתגובות של סטרימינג של אירועים שנשלחים מהשרת (SSE). ‫EVENT_FLOW_RESP מציין את זרימת התגובה של SSE (מופעלת פעם אחת לכל הודעת תגובה). ‫EVENT_FLOW_END מסמן את סוף שידור ה-SSE. בשלב הזה, טווחי הזמן האלה לא כוללים מאפייני ברירת מחדל. הם מופיעים בדוח המעקב כטווחי זמן עם שמות, כדי להציג את שלבי ה-SSE של ה-proxy.

מאפייני ברירת מחדל של משאבים

הכלל חל על: OpenTelemetry בלבד. הסעיף הזה לא חל על ההגדרה של OpenCensus.

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

הערה: הגישה שמבוססת על OpenTelemetry (פרוטוקול המעקב OTLP) נתמכת רק ב-Apigee ‏ (ApigeeX). הוא לא נתמך ב-Apigee Hybrid.

מאפיין	תיאור
`service.name`	ערך קבוע `apigee.googleapis.com`.
`service.instance.id`	מזהה של מופע מעבד ההודעות שיצר את הטווח. השדה מושמט אם זהות ה-pod של זמן הריצה לא זמינה.
`cloud.provider`	תמיד `gcp`.
`cloud.platform`	תמיד `gcp_apigee`.
`cloud.region`	האזור שבו מתארחת סביבת זמן הריצה של Apigee. אם לא מוגדר אזור, ברירת המחדל היא `global`.
`cloud.resource_id`	נתיב משאב Apigee מוגדר במלואו בפורמט `/apigee.googleapis.com/organizations/ORG/environments/ENV`.
`gcp.apigee.organization`	שם הארגון ב-Apigee.
`gcp.apigee.environment`	שם הסביבה ב-Apigee.
`gcp.project_id`	מזהה הפרויקט Google Cloud . האירוע הזה מופעל רק כשהייצואן הוא `OPEN_TELEMETRY_CLOUD_TRACE`.

סוגי טווחים

חל על: ההגדרות של OpenTelemetry ושל OpenCensus.

‫Apigee פולט טווחים עם הערכים הבאים של SpanKind:

`SpanKind`	טווחים שמופקים עם הסוג הזה
`SERVER`	טווח ה-proxy הבסיסי (אחד לכל הפעלה של proxy), שמייצג את הבקשה הנכנסת שהתקבלה בסביבת זמן הריצה של Apigee.
`INTERNAL`	כל שאר ה-spans, כולל spans של זרימה (לדוגמה, `RESP_SENT` ו-`PROXY_POST_RESP_SENT`) וכל span של שלב במדיניות (לדוגמה, AssignMessage, ‏ VerifyAPIKey,‏ ServiceCallout, ‏ JavaScript, ‏ KeyValueMapOperations).

‫Apigee לא פולט טווחים של CLIENT, PRODUCER או CONSUMER. בפרט, שיחות יוצאות מ-Apigee אל ה-backend של היעד לא מופיעות כטווחים נפרדים של CLIENT. השיחה היוצאת מיוצגת בטווחים הקיימים של זרימת INTERNAL, והכותרת traceparent מועברת אל היעד כדי ששירות היעד יוכל להפיק טווח SERVER משלו ולהצטרף לאותו מעקב.

משתנים בטווח `RESP_SENT`

המשתנים הבאים גלויים בתג RESP_SENT. בעמודה OTEL semantic variable מוצג השם של המוסכמה הסמנטית של OpenTelemetry שמשמשת כשערך המשתנה spanSemantics הוא OTEL. בעמודה Attribute מוצג שם המאפיין מדור קודם.

משתנה מדור קודם	משתנה סמנטי של OTEL	מאפיין	תיאור
`REQUEST_URL`	`url.full`	`request.url`	כתובת ה-URL המלאה של בקשת הלקוח הנכנסת שהתקבלה על ידי ה-proxy.
`REQUEST_VERB`	`http.request.method`	`request.verb`	פועל ה-HTTP של בקשת הלקוח הנכנסת (לדוגמה, `GET` או `POST`).
`RESPONSE_STATUS_CODE`	`http.response.status_code`	`response.status.code`	קוד הסטטוס של התגובה שהוחזר על ידי שרת היעד.
`ROUTE_NAME`	`gcp.apigee.route.name`	`route.name`	השם של כלל הניתוב שבחר את היעד לבקשה הזו.
`ROUTE_TARGET`	`gcp.apigee.route.target`	`route.target`	השם של נקודת הקצה של היעד שנבחרה על ידי כלל המסלול.
`TARGET_BASE_PATH`	`gcp.apigee.target.basepath`	`target.basepath`	חלק נתיב הבסיס של כתובת ה-URL של היעד.
`TARGET_HOST`	`server.address`	`target.host`	שם המארח של שרת היעד שאליו מתבצעת פנייה דרך ה-proxy.
`TARGET_IP`	`server.address`	`target.ip`	כתובת ה-IP של שרת היעד.
`TARGET_NAME`	`gcp.apigee.target.name`	`target.name`	השם של נקודת הקצה של היעד שהוגדרה ב-API proxy.
`TARGET_PORT`	`server.port`	`target.port`	יציאת TCP שמשמשת לחיבור לשרת היעד.
`TARGET_RECEIVED_END_TIMESTAMP`	`gcp.apigee.target.received_end_timestamp`	`target.received.end.timestamp`	חותמת זמן (במילישניות מאז ראשית זמן יוניקס) שבה ה-proxy סיים לקבל את התגובה משרת היעד.
`TARGET_RECEIVED_START_TIMESTAMP`	`gcp.apigee.target.received_start_timestamp`	`target.received.start.timestamp`	חותמת זמן (אלפיות שנייה מאז תקופת ה-Epoch) שבה ה-proxy התחיל לקבל את התגובה משרת היעד.
`TARGET_SENT_END_TIMESTAMP`	`gcp.apigee.target.sent_end_timestamp`	`target.sent.end.timestamp`	חותמת זמן (במילישניות מאז ראשית זמן יוניקס) שבה ה-proxy סיים לשלוח את הבקשה לשרת היעד.
`TARGET_SENT_START_TIMESTAMP`	`gcp.apigee.target.sent_start_timestamp`	`target.sent.start.timestamp`	חותמת זמן (במילישניות מאז ראשית זמן יוניקס) שבה ה-proxy התחיל לשלוח את הבקשה לשרת היעד.
`TARGET_SSL_ENABLED`	`gcp.apigee.target.ssl_enabled`	`target.ssl.enabled`	ערך בוליאני שמציין אם החיבור לשרת היעד השתמש ב-TLS.
`TARGET_URL`	`url.full`	`target.url`	כתובת ה-URL המלאה של שרת היעד שאליו מתחבר ה-proxy.

משתנים בטווח `PROXY_POST_RESP_SENT`

המשתנים הבאים מוצגים בתג PROXY_POST_RESP_SENT. בעמודה OTEL semantic variable מופיע השם של המוסכמה הסמנטית של OpenTelemetry שנעשה בה שימוש כש-spanSemantics מוגדר כ-OTEL. בעמודה Attribute מופיע שם המאפיין מדור קודם.

משתנה מדור קודם	משתנה סמנטי של OTEL	מאפיין	תיאור
`API_PROXY_REVISION`	`gcp.apigee.proxy.revision`	`apiproxy.revision`	מספר הגרסה של proxy ל-API שטיפל בבקשה.
`APIPROXY_NAME`	`gcp.apigee.proxy.name`	`apiproxy.name`	שם ה-proxy ל-API שטיפל בבקשה.
`CLIENT_RECEIVED_END_TIMESTAMP`	`gcp.apigee.client.received_end_timestamp`	`client.received.end.timestamp`	חותמת זמן (במילישניות מאז ראשית זמן יוניקס) שבה ה-proxy סיים לקבל את הבקשה מהלקוח.
`CLIENT_RECEIVED_START_TIMESTAMP`	`gcp.apigee.client.received_start_timestamp`	`client.received.start.timestamp`	חותמת זמן (במילישניות מאז ראשית זמן יוניקס) שבה ה-proxy התחיל לקבל את הבקשה מהלקוח.
`CLIENT_SENT_END_TIMESTAMP`	`gcp.apigee.client.sent_end_timestamp`	`client.sent.end.timestamp`	חותמת זמן (אלפיות שנייה מאז תקופת ה-Epoch) שבה ה-proxy סיים לשלוח את התשובה ללקוח.
`CLIENT_SENT_START_TIMESTAMP`	`gcp.apigee.client.sent_start_timestamp`	`client.sent.start.timestamp`	חותמת זמן (אלפיות שנייה מאז תקופת ה-Epoch) שבה ה-proxy התחיל לשלוח את התשובה ללקוח.
`ENVIRONMENT_NAME`	`gcp.apigee.environment`	`environment.name`	השם של סביבת Apigee שבה הופעל ה-proxy.
`FAULT_SOURCE`	`gcp.apigee.fault_source`	`message.header.X-Apigee-fault-source`	מקור התקלה אם מתרחשת שגיאה במהלך הביצוע של ה-proxy. השדה הזה מאוכלס רק בתהליכים עם שגיאות.
`IS_ERROR`	`gcp.apigee.is_error`	`is.error`	ערך בוליאני שמציין אם הביצוע של ה-proxy הסתיים בתהליך שגיאה.
`MESSAGE_ID`	`gcp.apigee.message.id`	`message.id`	מזהה ייחודי שהוקצה לבקשה על ידי Apigee. המזהה הזה שימושי לצורך קורלציה בין יומנים ובין טווחי מעקב.
`MESSAGE_STATUS_CODE`	`http.response.status_code`	`message.status.code`	קוד הסטטוס של התגובה הסופית, כולל קודים של שיחות ללא יעדים ושל תהליכי שגיאה.
`PROXY_BASE_PATH`	`http.route`	`proxy.basepath`	נתיב הבסיס של proxy ל-API שתאם לבקשה הנכנסת.
`PROXY_CLIENT_IP`	`client.address`	`proxy.client.ip`	כתובת ה-IP של הלקוח ששלח את הבקשה לשרת ה-proxy.
`PROXY_NAME`	`gcp.apigee.proxy.name`	`proxy.name`	השם של נקודת הקצה של ה-proxy ב-API proxy שטיפלה בבקשה.
`PROXY_PATH_SUFFIX`	`url.path`	`proxy.pathsuffix`	החלק בנתיב כתובת ה-URL של הבקשה שמופיע אחרי נתיב הבסיס של ה-proxy.
`PROXY_URL`	`url.full`	`proxy.url`	כתובת ה-URL המלאה של נקודת הקצה של ה-proxy כפי שהתקבלה מהלקוח.

מערכות נתמכות של מעקב מבוזר

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

מערכות מבוזרות למעקב	תיאור
‫Cloud Trace עם OpenTelemetry	הפתרון הזה מתאים למשתמשים שרוצים הגדרה פשוטה עם OpenTelemetry, ומערכת העורף העיקרית או היחידה למעקב שלהם היא Cloud Trace. כדי לשלוח נתוני מעקב ל-Cloud Trace באמצעות OpenTelemetry: הגדרת זמן הריצה של Apigee ל-Cloud Trace הפעלת מעקב מבוזר ב-Cloud Trace באמצעות OpenTelemetry. הערה: אתם אחראים לכל העלויות שקשורות לשליחת נתוני מעקב ל-Cloud Trace. פרטים נוספים מופיעים בדפים תמחור ומכסות.
‫OpenTelemetry Collector	ניהול של OpenTelemetry Collector כדי לשלוט באיסוף ובאחסון של נתוני מעקב. האפשרות הזו מתאימה במיוחד אם אתם צריכים לשלוח נתונים לכמה מערכות (כולל מערכות שאינן של Google) או להתאים אישית את אופן העיבוד, הקיבוץ או השיפור של הנתונים. כדי לשלוח נתוני מעקב אל OpenTelemetry Collector: פורסים ומנהלים OpenTelemetry Collector, כמו שמתואר במאמר בנושא OpenTelemetry Collector. הפעלת מעקב מבוזר עבור OpenTelemetry Collector. במאמר שיקולים לשימוש ב-OpenTelemetry Collector מפורטות הדרישות בנוגע לנגישות לרשת, ל-TLS ולתעבורה שצריך לעמוד בהן לפני שמפעילים את האפשרות הזו.
‫Cloud Trace עם OpenCensus	כדי לשלוח נתוני מעקב ל-Cloud Trace באמצעות OpenCensus, מבצעים את הפעולות הבאות: הגדרת זמן הריצה של Apigee ל-Cloud Trace‏ (OpenCensus) הפעלת מעקב מבוזר ב-Cloud Trace באמצעות OpenCensus הערה: אתם אחראים לכל העלויות שקשורות לשליחת נתוני מעקב ל-Cloud Trace. פרטים נוספים מופיעים בדפים תמחור ומכסות.
‫Jaeger עם OpenCensus	כדי לשלוח נתוני מעקב ל-Jaeger באמצעות OpenCensus, צריך להפעיל מעקב מבוזר ב-Jaeger.

משתני סביבה

התהליכים שבדף הזה משתמשים במשתני הסביבה הבאים. מומלץ להגדיר אותם בסביבה לפני שמתחילים.

TOKEN="Authorization: Bearer $(gcloud auth application-default print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

כאשר:

‫TOKEN מגדיר את כותרת האימות עם אסימון Bearer. משתמשים בהדר הזה כשקוראים לממשקי Apigee API. מידע נוסף מופיע בדף העיון של הפקודה print-access-token.
‫ENV_NAME הוא שם של סביבה בארגון.
‫PROJECT_ID הוא מזהה הפרויקט Google Cloud .

הגדרת זמן הריצה של Apigee לשימוש ב-OpenTelemetry או ב-OpenCensus

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

ב-OpenTelemetry, זמן הריצה של Apigee מזהה את פורמט הכותרת של הקשר למעקב W3C, כולל הכותרות traceparent, tracestate ו-baggage.

הערה: אין תמיכה בכותרות B3 ב-OpenTelemetry. כשמגדירים את זמן הריצה של Apigee ל-OpenTelemetry, B3 כותרות ההפצה (לדוגמה, x-b3-traceid,‏ x-b3-spanid,‏ x-b3-sampled,‏ x-b3-parentspanid,‏ x-b3-flags והטופס של כותרת אחת b3) מוזנחות, גם אם הן מופיעות בבקשה הנכנסת. רק כותרות ההקשר של מעקב W3C (‏traceparent, ‏tracestate ו-baggage) נלקחות בחשבון לצורך העברת הקשר. ב-OpenTelemetry, המערכת מתעלמת מכותרות B3, בין אם הלקוח מעביר אותן או שהן נוצרות באופן עצמאי על ידי Service mesh כמו Istio. הסיבה לכך היא שהקשר של מעקב W3C קודם ל-B3, ולכן המערכת מתעלמת גם מכותרות B3 ש-Istio מוסיף. אם כרגע מתקבלות מהמערכות במעלה הזרם רק כותרות B3, צריך להגדיר אותן כך שיתקבלו גם כותרות W3C traceparent, או להשתמש בהגדרת OpenCensus במקום זאת.

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

בקשות לנקודת קצה של יעד (יעד בקצה העורפי), כולל יעדים של כללי ניתוב
ServiceCallout
IntegrationCallout
VerifyIAM
הגנה מ-AI גנרטיבי (SanitizeUserPrompt ו-SanitizeModelResponse)
SemanticCache (SemanticCacheLookup ו-SemanticCachePopulate)
‫JavaScript‏ (httpClient.send)
‫ModelRouter (דרך היעד שהוא בוחר)
סטרימינג של תגובות של אירועים שנשלחים מהשרת (SSE)

במדיניות ובזרימות האלה, Apigee מעביר את כותרות ההקשר של מעקב W3C ‏ (traceparent, ‏ tracestate ו-baggage) כשמשתמשים ב-OpenTelemetry, ואת הכותרות B3 כשמשתמשים ב-OpenCensus.

הגדרת דרישות מוקדמות ל-Cloud Trace‏ (OpenTelemetry)

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

הגדרת זמן הריצה של ApigeeX ל-Cloud Trace

כדי להגדיר את זמן הריצה של Apigee ל-Cloud Trace, צריך להפעיל את ממשקי ה-API הבאים בפרויקט Google Cloud :

‫Cloud Trace API (trace.googleapis.com)
‫Telemetry API (telemetry.googleapis.com)
‫Service Usage API (serviceusage.googleapis.com)

הפעלת ממשקי ה-API האלה מאפשרת לפרויקט Google Cloud לקבל נתוני מעקב דרך OpenTelemetry ממקורות מאומתים.

כדי להפעיל את ממשקי ה-API:

במסוף Google Cloud , עוברים אל APIs and Services:
כניסה אל APIs and Services
לוחצים על Enable APIs and Services (הפעלת ממשקי API ושירותים) כדי לפתוח את ספריית ה-API.
בספריית ה-API, מפעילים את Cloud Trace API, את Telemetry API ואת Service Usage API. אפשר למצוא כל API על ידי חיפוש לפי שם (לדוגמה, Telemetry API) בסרגל החיפוש של API Library.

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

roles/telemetry.tracesWriter
roles/serviceusage.serviceUsageConsumer

חשבון השירות הספציפי תלוי בסביבת Apigee שלכם:

‫ApigeeX (לא היברידי): מעניקים את התפקידים לסוכן השירות של Apigee, שהוא P4SA (חשבון שירות לכל מוצר לכל פרויקט) בניהול Google, שמוקצה אוטומטית לפרויקט על ידי Apigee. חשבון סוכן השירות הוא בפורמט service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com.

במאמר איך נותנים תפקידים ב-IAM באמצעות מסוף Google Cloud מוסבר איך עושים את זה.

הפעלת מעקב מבוזר (OpenTelemetry)

לפני שמפעילים מעקב מבוזר, צריך ליצור את משתני הסביבה הנדרשים.

הפעלת מעקב מבוזר ב-Cloud Trace

בדוגמה הבאה אפשר לראות איך מפעילים מעקב מבוזר ב-Cloud Trace באמצעות OpenTelemetry:

מריצים את הקריאה הזו ל-Apigee API:
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"OPEN_TELEMETRY_CLOUD_TRACE",
          "endpoint": "'"$PROJECT_ID"'",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL"
        }'
```
גוף הבקשה בדוגמה מורכב מהרכיבים הבאים:
- כדי לתמוך ב-Cloud Trace באמצעות OpenTelemetry, הפרמטר exporter מוגדר ל-OPEN_TELEMETRY_CLOUD_TRACE והפרמטר traceProtocol מוגדר ל-OTLP.
- הערך של samplingRate הוא 0.05. המשמעות היא שכ-5% מהקריאות ל-API נשלחות ל-distributed tracing. ב-OpenTelemetry, אפשר לציין שיעור דגימה של עד 1.0 (100%). מידע נוסף זמין במאמר בנושא שיקולים לגבי ביצועים.
  הערה: התג samplingRate חל רק על בקשות שלא כוללות כותרת traceparent של W3C. כשבקשה מגיעה עם כותרת traceparent, מערכת Apigee משתמשת בדגל הדגימה בכותרת הזו במקום ב-samplingConfig המקומי. לפרטים נוספים אפשר לעיין במאמר בנושא קדימות של כותרות על פני הגדרות מקומיות.
- הפרמטר endpoint מוגדר ל Google Cloud מזהה הפרויקט שאליו אמורים להגיע נתוני העקבות (מחרוזת של מזהה פרויקט בלבד, לא כתובת URL).
  הערה: הפרמטר endpoint צריך להיות מוגדר לפרויקט שמשויך לחשבון השירות שהוגדר בשלב ההגדרה.
  
  התראה: אחרי שמגדירים את נקודת הקצה של פרויקט Cloud Trace, אי אפשר לשנות אותה.
- הפרמטר spanSemantics הוא אופציונלי, והוא שולט במאפיין ובשם של הטווח שמשמשים בטווחים שמועברים. ערכים נתמכים:
  - ‫LEGACY (ברירת מחדל): משתמשים בשמות של יחידות לוגיות למעקב ומאפיינים היסטוריים של Apigee שמוצגים בעמודה Attribute בטבלאות של המשתנים.
  - ‫OTEL: שימוש בשמות של מוסכמות סמנטיות של OpenTelemetry שמופיעים בעמודה OTEL semantic variable. הערך של traceProtocol חייב להיות OTLP.
תגובה מוצלחת תיראה כך:
```
{
  "exporter": "OPEN_TELEMETRY_CLOUD_TRACE",
  "endpoint": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP",
  "spanSemantics": "OTEL"
}
```

הפעלת מעקב מבוזר ב-OpenTelemetry Collector

כדי להפעיל מעקב מבוזר עבור OpenTelemetry Collector בניהול הלקוח, מריצים את הקריאה הבאה ל-Apigee API:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "http://my-otel-collector.example.com:4318/v1/traces",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05},
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL"
        }'

גוף הבקשה בדוגמה מורכב מהרכיבים הבאים:

כדי לתמוך ב-OpenTelemetry Collector בניהול הלקוח, הפרמטר exporter מוגדר ל-OPEN_TELEMETRY_COLLECTOR והפרמטר traceProtocol מוגדר ל-OTLP.
הפרמטר endpoint מוגדר לכתובת ה-URL המלאה של HTTP/HTTPS של נקודת הקצה להעברת נתונים בפורמט OTLP של OpenTelemetry Collector (לדוגמה, http://my-otel-collector.example.com:4318/v1/traces). בניגוד ל-Cloud Trace exporter, שמקבל מזהה פרויקט Google Cloud , ה-OPEN_TELEMETRY_COLLECTOR exporter דורש כתובת URL מלאה שכוללת סכימה, מארח, יציאה ונתיב. בניגוד לנקודת הקצה של Cloud Trace, ‏ endpoint של OpenTelemetry Collector ניתן לשינוי: אפשר להגדיר אותו מחדש בהמשך עם PATCH אחר ל-traceConfig.
הערך של samplingRate הוא 0.05. המשמעות היא שכ-5% מהקריאות ל-API נשלחות ל-distributed tracing. מידע נוסף זמין במאמר בנושא שיקולים לגבי ביצועים.
הערה: התג samplingRate חל רק על בקשות שלא כוללות כותרת traceparent של W3C. כשבקשה מגיעה עם כותרת traceparent, מערכת Apigee משתמשת בדגל הדגימה בכותרת הזו במקום ב-samplingConfig המקומי. לפרטים נוספים אפשר לעיין במאמר בנושא קדימות של כותרות על פני הגדרות מקומיות.
הפרמטר otelCollectorSecurityScheme הוא אופציונלי, וכברירת מחדל הוא מוגדר לערך NONE. מגדירים את הערך MTLS כדי להפעיל Mutual TLS (mTLS) הדדי בין Apigee לבין ה-Collector. במאמר הגדרת mTLS עבור OpenTelemetry Collector מפורטים השדות הנדרשים mtlsConfig וגוף בקשת ה-API המלא.

תגובה מוצלחת תיראה כך:

{
  "exporter": "OPEN_TELEMETRY_COLLECTOR",
  "endpoint": "http://my-otel-collector.example.com:4318/v1/traces",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  },
  "traceProtocol": "OTLP",
  "spanSemantics": "OTEL"
}

שיקולים לשימוש ב-OpenTelemetry Collector

לפני שמפעילים מעקב מבוזר ב-OpenTelemetry Collector בניהול הלקוח, צריך לעיין בדרישות הבאות.

נגישות לרשת

מוודאים ש-Apigee יכול לגשת אל OpenTelemetry Collector.
כדי להגיע למרכז נתונים שלא חשוף באינטרנט הציבורי, צריך להשתמש ב-Private Service Connect ‏ (PSC).
אם יש שרת proxy קדימה בהגדרה שלכם, צריך להגדיר אותו ב-OpenTelemetry Collector. החיבורים ממעבד ההודעות אל OpenTelemetry Collector הם תמיד ישירים.

פרוטוקול העברה

רק פרוטוקול התעבורה OTLP/HTTP נתמך ב-OpenTelemetry Collectors (יציאה 4318 ונתיב /v1/traces לפי מוסכמת OTLP). אין תמיכה ב-OTLP/gRPC (יציאה 4317).

TLS ו-mTLS

‫Apigee תומך בשני מנגנוני אבטחה לחיבור אל OpenTelemetry Collector, שמוגדרים באמצעות otelCollectorSecurityScheme ב-traceConfig:

ללא אבטחה (HTTP) (NONE, ברירת המחדל): Apigee מתחבר לאוסף באמצעות HTTP ללא TLS הדדי.
‫mTLS‏ (MTLS): ‏ TLS בו-זמני, כך שהמאסף יכול גם לאמת את Apigee כלקוח. כדי להפעיל mTLS, מגדירים את otelCollectorSecurityScheme ל-MTLS ב-traceConfig ומספקים mtlsConfig שמפנה למאגרי מפתחות ולמאגרי אישורים שמנוהלים על ידי Apigee. הוראות להגדרה מקצה לקצה מפורטות במאמר הגדרת mTLS עבור OpenTelemetry Collector.

הגדרת mTLS עבור OpenTelemetry Collector

פרוטוקול TLS דו-כיווני (mTLS) מאפשר ל-OpenTelemetry Collector לאמת את זמן הריצה של Apigee כלקוח, בנוסף לאימות של Apigee את אישור השרת של ה-Collector.

הערה: שמות מאגרי המפתחות, מאגרי האישורים והכינויים שמופיעים בדוגמאות הבאות (לדוגמה, otel-mtls,‏ mp-client ו-otel-mtls-truststore) הם רק דוגמאות. אתם יכולים להשתמש בשמות שתבחרו.

לפני שמגדירים mTLS, צריך לוודא שמתקיימות הדרישות המוקדמות הבאות:

האוסף מוגדר לדרוש אימות של אישור לקוח (לדוגמה, ההגדרה tls.client_ca_file של OpenTelemetry Collector) והוא נפרס עם קובץ רשות אישורים (CA) שמכיל את שרשרת האישורים שהעליתם בשלב 1 של ההגדרה.
ה-endpoint משתמש בסכימת https://.
הערך בעמודה exporter הוא OPEN_TELEMETRY_COLLECTOR והערך בעמודה traceProtocol הוא OTLP. ‫mTLS לא חל על OPEN_TELEMETRY_CLOUD_TRACEהכלי לייצוא, שמאמת באמצעות Google Cloud OAuth במקום זאת.

שלב 1: העלאת מפתח הלקוח והאישור

יוצרים keystore לאישור הלקוח של Apigee שהמאסף מאמת, ואז מעלים את המפתח והאישור ככינוי:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases?alias=mp-client&format=keycertfile" \
    -X POST \
    -F "keyFile=@client.key" \
    -F "certFile=@client.crt"

קובץ client.crt צריך להיות חתום על ידי רשות אישורים שרכיב האיסוף tls.client_ca_file סומך עליה. במקרה של הגדרה עם חתימה עצמית, client.crt יכול להיות אותו קובץ שבו הכלי לאיסוף נתונים משתמש כ-client_ca_file.

שלב 2: מעלים את אישור השרת של הכלי לאיסוף נתונים

יוצרים truststore שזמן הריצה של Apigee משתמש בו כדי לאמת את אישור השרת של האוסף, ואז מעלים את אישור ה-CA של האוסף בתור כינוי CERT:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores \
    -X POST \
    -d '{ "name": "otel-mtls-truststore" }'

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls-truststore/aliases?alias=server-ca&format=keycertfile" \
    -X POST \
    -F "certFile=@server-ca.pem"

שלב 3: הפעלת mTLS ב-`traceConfig`

מבצעים PATCH ל-traceConfig כדי להגדיר את תוכנית האבטחה ל-MTLS ומפנים אל מאגר המפתחות ומאגר האישורים שיצרתם:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter": "OPEN_TELEMETRY_COLLECTOR",
          "endpoint": "https://my-otel-collector.example.com:4318/v1/traces",
          "traceProtocol": "OTLP",
          "spanSemantics": "OTEL",
          "otelCollectorSecurityScheme": "MTLS",
          "mtlsConfig": {
            "keyStore":   "otel-mtls",
            "keyAlias":   "mp-client",
            "trustStore": "otel-mtls-truststore"
          }
        }'

לאובייקט mtlsConfig יש שלושה שדות חובה:

‫keyStore: שם מאגר המפתחות שמכיל את מפתח הלקוח ואת האישור של Apigee משלב 1 (לדוגמה, otel-mtls). כדי להשתמש בהפניה של Apigee, מציינים ref://REFERENCE_NAME.
‫keyAlias: השם של הכינוי KEY_CERT בתוך keyStore (לדוגמה, mp-client).
‫trustStore: השם של מאגר המפתחות שמכיל את אישור ה-CA של שרת האוסף משלב 2 (לדוגמה, otel-mtls-truststore). כדי להשתמש בהפניה של Apigee במקום זאת, מציינים ref://REFERENCE_NAME.

מערכת Apigee מבצעת את האימות הבא ב-traceConfig כש-otelCollectorSecurityScheme הוא MTLS:

הערך של exporter חייב להיות OPEN_TELEMETRY_COLLECTOR.
הערך של traceProtocol חייב להיות OTLP.
ב-endpoint צריך להשתמש בסכימה https://.
צריך למלא את כל שלושת השדות mtlsConfig. אם חסר שדה כלשהו, מוחזרת שגיאת HTTP 400.
מאגרי המפתחות, הכינויים וההפניות חייבים להיות קיימים. אם חסרים משאבים, מוחזרת שגיאת HTTP 400.

החלפת המפתח או האישור של הלקוח

כדי לבצע רוטציה של מפתח או אישור לקוח בלי לשנות את traceConfig, מעלים חומר מפתח חדש לכינוי mp-client הקיים באמצעות PUT:

curl -H "$TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/keystores/otel-mtls/aliases/mp-client" \
    -X PUT \
    -F "keyFile=@client-v2.key" \
    -F "certFile=@client-v2.crt"

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

קריטריוני דגימה

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

כותרת של הקשר למעקב של W3C

במסגרת ההגדרה של OpenTelemetry, סביבת זמן הריצה מכבדת את הכותרת W3C trace context traceparent. הבייט האחרון של traceparent (בייט trace-flags) מכיל את הדגל sampled: ערך של 01 מציין שהמתקשר כבר החליט לתעד את המעקב, וערך של 00 מציין שהוא לא החליט.

ההמלצות של מפרט הקשר של W3C trace לגבי הדגל sampled הן שרכיב צריך להתחשב בדגל sampled הנכנס כשהוא מקבל החלטה לגבי הקלטה, ולשקף החלטה סופית לגבי הקלטה בדגל. ‫Apigee פועל לפי ההמלצות הבאות: הוא מתחשב בדגל הדגימה הנכנס כשהוא מחליט אם לתעד מעקב (ראו עדיפות של כותרת על פני הגדרה מקומית), ומגדיר את דגל הדגימה בכותרת traceparent שהוא מעביר לשירותים במורד הזרם כדי לשקף אם הבקשה מתועדת. כאמצעי בקרה אבטחתי נגד מעקב לא רצוי שמופעל על ידי הדגל הנכנס, צריך להגדיר את sampler ל-OFF (ראו השבתה של ההגדרה של מעקב מבוזר), מה שמשבית את המעקב גם לבקשות שבהן הדגל traceparent מוגדר.

קדימות של כותרת על פני הגדרה מקומית

כשבקשה נכנסת כוללת כותרת traceparent, סביבת זמן הריצה של Apigee משתמשת בדגל הדגימה מהכותרת הזו במקום בדגל המקומי samplingConfig. בקשה שהדגל שלה מוגדר לערך 01 תמיד תתועד, ובקשה שהדגל שלה מוגדר לערך 00 לא תתועד. רמת הגישה samplingConfig ברמת הסביבה חלה רק על בקשות שמגיעות בלי כותרת traceparent.

השבתת התיעוד

כדי להשבית את המעקב לכל שרת proxy בסביבה (לא כולל שינויים בשרת proxy), צריך להגדיר את sampler לערך OFF בסביבת traceConfig. השבתת ההגדרה של מעקב מבוזר

שינויים בהגדרות של כל שרת proxy

כדי להפעיל מעקב רק עבור קבוצת משנה של שרתי proxy בסביבה, משאירים את הסביבה samplingConfig עם הערך sampler שמוגדר ל-OFF ויוצרים שינוי בהגדרות של כל שרת proxy (עם הערך sampler שמוגדר ל-PROBABILITY והערך samplingRate שמוגדר לערך שאינו אפס) עבור כל שרת proxy שרוצים לעקוב אחריו. אפשר לעיין במאמר בנושא שינוי הגדרות המעקב של שרתי proxy של API.

ההשפעה של תדירות הדגימה על הביצועים

ההגדרותsamplingRate שקובעים משפיעות ישירות על הביצועים בזמן הריצה. כל בקשה שנכללת במדגם גורמת לעבודת מעבד (CPU) נוספת במעבד בקשות (יצוא וייצוא של יחידות לוגיות למעקב) ומוסיפה חביון לנתיב הבקשה. ככל ששיעור הדגימה עולה, כך עולה נפח התנועה שמתבצעת לגביו מעקב לכל MP, מה שיכול להפחית את התפוקה ולהגדיל את זמן האחזור (p95, ‏ p99). ההשפעה גדלה עם נפח התנועה: בשיעורי בקשות נמוכים, התקורה בדרך כלל זניחה, אבל בשיעורי בקשות גבוהים, שיעור דגימה גבוה יכול להפחית באופן משמעותי את התפוקה בת קיימא ולדרוש קיבולת נוספת של MP. בנקודות השוואה פנימיות, הפעלה ב-samplingRate=1.0 (100% דגימה) בתנאי עומס תנועה כבד מתמשך הפחיתה את קצב העברת הנתונים בכ-15% בהשוואה להפעלה עם השבתת המעקב.

ככלל, מומלץ להגדיר את samplingRate לערך נמוך (למשל 0.1 או פחות) בסביבת הייצור, ולהגדיל אותו רק עבור שרתי proxy ספציפיים באמצעות הגדרות ברירת מחדל שמוגדרות מחדש לכל שרת proxy כשנדרשת רמת חשיפה גבוהה יותר. לפירוט של ההשפעה הצפויה וההנחיות לגבי הקיבולת, אפשר לעיין במאמר בנושא שיקולי ביצועים.

שיקולי ביצועים

כשמפעילים מעקב מבוזר בסביבת זמן ריצה של Apigee, צפויה השפעה על הביצועים. ההשפעה יכולה להתבטא בשימוש מוגבר בזיכרון, בדרישות מעבד מוגברות ובזמן אחזור מוגבר. היקף ההשפעה תלוי במורכבות של שרת ה-API (לדוגמה, מספר המדיניות), בשיעור הדגימה ההסתברותית (מוגדר כ-samplingRate) והכי חשוב, בנפח התנועה שנבדק ביחס ליכולת הייצוא של טווח מעבד ההודעות (MP).

ל-Apigee MP יש קצב ייצוא סופי של טווחים. בהגדרת ברירת המחדל, כל MP יכול לייצא באופן קבוע כ-820 טווחים בשנייה. ביצוע טיפוסי של שרת proxy ל-API יוצר בערך 10 טווחים (proxy preflow, target flow, postflows, attached policies), כך שמעבד הודעות יחיד יכול לעקוב באופן קבוע אחרי כ-82 בקשות בשנייה בשיעור דגימה של 100%. הגדלת מספר העותקים של ה-MP מגדילה את התקרה המצטברת באופן לינארי.

בטבלה הבאה מסוכמת ההשפעה הצפויה ב-samplingRate=1.0 (סבירות של 100%) בשני מצבי תנועה:

הערה: הנתונים בטבלה הבאה מבוססים על ההנחה שבבקשות הנכנסות לא מופיעה כותרת W3C traceparent. בקשות שמגיעות עם כותרת traceparent שדגימת הבייטים שלה מופעלת (1) תמיד יעברו מעקב, והן מקבלות עדיפות על פני samplingRate שהוגדר, מה שיכול לשנות את נפח המעקב בפועל ואת ההשפעה על הביצועים.

מצב התנועה (לכל נקודת מעקב)	ההשפעה הצפויה ב-`samplingRate=1.0`	הפעולה המומלצת
עומס תנועה קל (פחות מ-82 בקשות במעקב לשנייה לכל מעבד רב-ליבות)	התפוקה יורדת בכ-1-2%; זמן האחזור הממוצע עולה בכ-1%; זמן האחזור p99 עולה בכ-15-20%. בפועל, ההשפעה זניחה.	אפשר להפעיל ב-100%.
עומס תנועה כבד (הרבה מעל כ-82 בקשות במעקב לשנייה לכל MP)	התפוקה יורדת בכ-14%, זמן האחזור הממוצע עולה בכ-24%, זמן האחזור של p75 עולה בכ-52% ושיעור השגיאות עולה בכנקודת אחוז אחת.	אפשר להקטין את הערך `samplingRate` (לדוגמה, ל-`0.1` או ל-`0.05`), או להגדיל את מספר העותקים של ה-MP כך שכל MP ישרת פחות בקשות למעקב בשנייה.

בסביבות עם נפח תנועה גבוה ודרישות זמן אחזור נמוכות, שיעור הדגימה ההסתברותי המומלץ הוא 10% או פחות. אם רוצים להשתמש במעקב מבוזר כדי לפתור בעיות, כדאי להגדיל את הדגימה ההסתברותית (samplingRate) רק עבור שרתי proxy ספציפיים של API באמצעות החלפות לכל שרת proxy.

הגדרת זמני ריצה של Apigee ל-Cloud Trace‏ (OpenCensus)

סביבת זמן הריצה של Apigee וסביבת זמן הריצה של Apigee Hybrid תומכות במעקב מבוזר באמצעות Cloud Trace עם OpenCensus. אם אתם משתמשים ב-Jaeger, אתם יכולים לדלג על הקטע הזה ולעבור אל הפעלת מעקב מבוזר ב-Jaeger באמצעות OpenCensus.

הגדרת זמן הריצה של Apigee ל-Cloud Trace

כדי להגדיר את זמן הריצה של Apigee ל-Cloud Trace, צריך להפעיל את Cloud Trace API בפרויקט Google Cloud .

כדי להפעיל את ה-API:

במסוף Google Cloud , עוברים אל APIs and Services:
כניסה אל APIs and Services
לוחצים על Enable APIs and Services.
מפעילים את Cloud Trace API.

הגדרת זמן הריצה של Apigee Hybrid ל-Cloud Trace

כדי להגדיר את סביבת זמן הריצה של Apigee Hybrid ל-Cloud Trace, מפעילים את Cloud Trace API.

בנוסף להפעלת ה-API, צריך להוסיף את iam.gserviceaccount.com חשבון השירות כדי להשתמש ב-Cloud Trace עם סביבת זמן הריצה ההיברידית. כדי להוסיף את חשבון השירות, יחד עם התפקיד והמפתחות הנדרשים roles/cloudtrace.agent, מבצעים את השלבים הבאים:

יוצרים חשבון שירות חדש:

gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID

מוסיפים מדיניות IAM שמקושרת לחשבון שירות:

gcloud projects add-iam-policy-binding \
    PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/cloudtrace.agent --project PROJECT_ID

יוצרים מפתח לחשבון השירות ומעדכנים את overrides.yaml כמו שמתואר בשלבים הבאים.
יוצרים מַפְתח לחשבון השירות:
```
gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
```
מפתחות של חשבונות שירות מהווים סיכון אבטחה אם לא מנהלים אותם בצורה נכונה. באחריותכם לאבטח את המפתח הפרטי ולבצע פעולות אחרות שמתוארות במאמר שיטות מומלצות לניהול מפתחות לחשבונות שירות. אם אין לכם אפשרות ליצור מפתח לחשבון שירות, יכול להיות שהיצירה של מפתחות לחשבון שירות מושבתת בארגון שלכם. מידע נוסף מופיע במאמר בנושא ניהול משאבי ארגון עם אבטחה כברירת מחדל.
אם קיבלתם את המפתח של חשבון השירות ממקור חיצוני, אתם צריכים לאמת אותו לפני השימוש. מידע נוסף זמין במאמר בנושא דרישות אבטחה לגבי אישורים ממקורות חיצוניים.

מוסיפים את חשבון השירות לקובץ overrides.yaml.

envs:
 - name: ENV_NAME
   serviceAccountPaths:
     runtime: apigee-runtime.json
     synchronizer: apigee-sync.json
     udca: apigee-udca.json

כדי להחיל את השינויים על זמן הריצה, משתמשים ב-Helm:

helm upgrade ENV_NAME apigee-env/ \
    --namespace APIGEE_NAMESPACE \
    --set env=ENV_NAME \
    --atomic \
    -f overrides.yaml

הפעלת מעקב מבוזר (OpenCensus)

לפני שמפעילים מעקב מבוזר, צריך ליצור את משתני הסביבה הנדרשים.

הפעלת מעקב מבוזר ב-Cloud Trace באמצעות OpenCensus

בדוגמה הבאה אפשר לראות איך מפעילים מעקב מבוזר ב-Cloud Trace באמצעות OpenCensus:

מריצים את הקריאה הזו ל-Apigee API:
```
curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "exporter":"CLOUD_TRACE",
          "endpoint": "'"$PROJECT_ID"'",
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}
        }'
```
גוף הבקשה בדוגמה מורכב מהרכיבים הבאים:
- כדי לתמוך ב-Cloud Trace, הפרמטר exporter מוגדר לערך CLOUD_TRACE. ערך ברירת המחדל של הפרמטר traceProtocol, שלא צוין, הוא OpenCensus.
- הפרמטר endpoint מוגדר לפרויקט Google Cloud שאליו רוצים לשלוח את ה-trace.
- הערך של samplingRate הוא 0.1. המשמעות היא שכ-10% מהקריאות ל-API נשלחות למעקב מבוזר. ב-OpenCensus, שיעור הדגימה המקסימלי שניתן להגדרה הוא 0.5.
  התראה: אחרי שמגדירים את הפרמטר endpoint, אי אפשר לעדכן אותו.
תגובה מוצלחת תיראה כך:
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

הפעלת מעקב מבוזר עבור Jaeger באמצעות OpenCensus

בדוגמה הבאה אפשר לראות איך מפעילים מעקב מבוזר ב-Jaeger:

curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

בדוגמה הזו:

כדי לתמוך ב-Jaeger, הפרמטר exporter מוגדר ל-JAEGER. ערך ברירת המחדל של הפרמטר traceProtocol, שלא צוין, הוא OpenCensus.
הפרמטר endpoint מוגדר למיקום שבו Jaeger מותקן ומוגדר.
התראה: אחרי שמגדירים את הפרמטר endpoint, אי אפשר לעדכן אותו.
הערך של samplingRate הוא 0.4. המשמעות היא שכ-40% מהקריאות ל-API נשלחות למעקב מבוזר.

צפויים שינויים בביצועים כשמפעילים מעקב מבוזר בסביבת זמן ריצה של Apigee. ההשפעה יכולה לגרום לשימוש מוגבר בזיכרון, לדרישות מעבד מוגברות ולזמן אחזור מוגבר. היקף ההשפעה תלוי בחלקו במורכבות של proxy ל-API (לדוגמה, מספר המדיניות) ובשיעור הדגימה ההסתברותי (מוגדר כ-samplingRate). ככל ששיעור הדגימה גבוה יותר, כך ההשפעה על הביצועים גדולה יותר.

מידע נוסף זמין במאמר בנושא שיקולים לגבי ביצועים.

הערה: יש עיכוב בהפצת ההגדרות. תשובה מוצלחת של API ל-PATCH .../traceConfig מאשרת שהגדרת התצורה התקבלה על ידי מישור הבקרה. סביבת זמן הריצה של Apigee מבצעת בדיקות לגבי עדכוני הגדרות, ולכן שינוי בדרך כלל נכנס לתוקף בסביבת זמן הריצה תוך דקה עד שתיים בערך אחרי תגובת ה-API. כשבודקים שינוי בהגדרות, צריך להמתין עד לסיום חלון ההפצה הזה לפני שממשיכים בבדיקה. כדי לאשר את מצב מישור הבקרה, משתמשים בשדות revisionId ו-updateTime שמוחזרים על ידי ה-API (ראו הצגת ההגדרה של מעקב מבוזר).

צפייה בהגדרות של מעקב מבוזר

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

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

כשמריצים את הפקודה, אפשר לראות תגובה שדומה לזו:

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "my-gcp-project-id",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  },
  "revisionId": "7",
  "updateTime": "2026-06-08T14:25:13.512000Z"
}

הערך של revisionId גדל בכל עדכון מוצלח, והערך של updateTime משקף את חותמת הזמן של השרת של השינוי האחרון. משתמשים בשני השדות האלה כדי לוודא שמישור הבקרה קיבל עדכון הגדרה. שניהם מוחזרים גם בתגובה PATCH .../traceConfig.

עדכון ההגדרה של מעקב מבוזר

הפקודה הבאה מראה איך לעדכן את ההגדרה הקיימת של מעקב מבוזר ב-Cloud Trace:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.6}
        }'

כשמריצים את הפקודה, אפשר לראות תגובה שדומה לזו:

‫

{
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.6
  },
  "traceProtocol": "OTLP"
}

בדוגמה הזו, תדירות הדגימה מתעדכנת ל-0.6.

כדי לעדכן את ההגדרה של Jaeger, מגדירים את השדה exporter בבקשה לערך JAEGER.

השבתת ההגדרה של מעקב מבוזר

בדוגמה הבאה מוצג איך להשבית מעקב מבוזר שהוגדר ל-Cloud Trace:

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH \
    -d '{
          "samplingConfig": {"sampler": "OFF"}
        }'

הערה: הגדרת sampler לערך OFF משביתה את המעקב עבור כל בקשה בסביבה, כולל בקשות שמגיעות עם כותרת W3C traceparent שהדגל שלה לדגימה מוגדר. סביבת זמן הריצה מתייחסת רק ל-samplingRate כש-sampler הוא PROBABILITY. פרטים נוספים זמינים במאמר בנושא קריטריונים לדגימה.

כשמריצים את הפקודה, אפשר לראות תגובה שדומה לזו:

{
  "samplingConfig": {
    "sampler": "OFF"
  },
  "traceProtocol": "OTLP"
}

שינוי הגדרות איתור של שרתי proxy ל-API

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

בדוגמה הבאה מבוצעת החלפה של הגדרת המעקב המבוזר עבור ה-proxy ל-API‏ hello-world:

curl -s -H "$TOKEN" \
     https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

אפשר לשנות את ההגדרה כדי לפתור בעיות שספציפיות לשרת proxy ל-API בלי לשנות את ההגדרה של כל שרתי ה-proxy ל-API.

עדכון של ביטולי הגדרות מעקב

כדי לעדכן ביטול של הגדרות המעקב עבור שרת proxy ל-API או קבוצה של שרתי proxy ל-API, פועלים לפי השלבים הבאים:

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

curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides \
    -X GET

הפקודה הזו אמורה להחזיר תגובה דומה לזו שמוצגת בהמשך, שמכילה שדה name (שם) שמזהה את השרת או השרתים הפרוקסי הכפופים לביטול:

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

כדי לעדכן את ה-proxy, משתמשים בערך של השדה 'name' כדי לשלוח בקשת POST להגדרת הביטול של ה-proxy הזה,יחד עם ערכי השדות המעודכנים. לדוגמה:

curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1 \
    -X POST \
    -H "content-type:application/json" \
    -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

מחיקת שינויים בהגדרות המעקב

כדי למחוק ביטול של הגדרת המעקב עבור שרת proxy ל-API או קבוצה של שרתי proxy ל-API, מבצעים את השלבים הבאים:

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

curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides \
    -X GET

{
  "traceConfigOverrides": [
    {
      "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
      "apiProxy": "proxy1",
      "samplingConfig": {
        "sampler": "PROBABILITY",
        "samplingRate": 0.25
      }
    }
  ]
}

כדי למחוק את ה-proxy, משתמשים בערך של השדה 'name' כדי לשלוח בקשת DELETE להגדרת הביטול של ה-proxy הזה,יחד עם ערכי השדות המעודכנים. לדוגמה:
```
curl -s -H "$TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1 \
    -X DELETE \
```

פתרון בעיות של מעקב מבוזר

כדי לפתור בעיות שקשורות למעקב מבוזר:

כדי לוודא שההגדרה של מעקב מבוזר מתאימה לצרכים שלכם, בודקים אותה באמצעות traceConfig API.
מוודאים שלחשבון השירות יש את הרשאות ה-IAM (התפקידים) הנכונות בפרויקט היעד.
אם אתם משתמשים ב-Cloud Trace עם OpenTelemetry, כדאי לבדוק אם יש טווחי זמן נכנסים ושגיאות שקשורות להפעלת API או למכסות.
אם משתמשים ב-OpenTelemetry Collector בניהול הלקוח, מבצעים את הפעולות הבאות:
- מוודאים ש-Apigee יכול לגשת לנקודת הקצה של Collector. אם משתמשים ב-Private Service Connect ‏ (PSC), צריך לבדוק את ההגדרה שלו.
- בודקים את היומנים של OpenTelemetry Collector כדי לזהות בעיות בנתונים או בחיבור.
- מוודאים שאישור ה-TLS של כלי האיסוף תקין.
בודקים את יומני זמן הריצה של Apigee כדי לראות אם יש שגיאות בייצוא של נתוני מעקב.

הפעלת מעקב מבוזר קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

מבוא

משתני מעקב שמוגדרים כברירת מחדל בדוח המעקב

מאפייני ברירת מחדל של משאבים

סוגי טווחים

משתנים בטווח RESP_SENT

משתנים בטווח PROXY_POST_RESP_SENT

מערכות נתמכות של מעקב מבוזר

משתני סביבה

הגדרת זמן הריצה של Apigee לשימוש ב-OpenTelemetry או ב-OpenCensus

הגדרת דרישות מוקדמות ל-Cloud Trace‏ (OpenTelemetry)

הגדרת זמן הריצה של ApigeeX ל-Cloud Trace

הפעלת מעקב מבוזר (OpenTelemetry)

הפעלת מעקב מבוזר ב-Cloud Trace

הפעלת מעקב מבוזר ב-OpenTelemetry Collector

שיקולים לשימוש ב-OpenTelemetry Collector

נגישות לרשת

פרוטוקול העברה

TLS ו-mTLS

הגדרת mTLS עבור OpenTelemetry Collector

שלב 1: העלאת מפתח הלקוח והאישור

שלב 2: מעלים את אישור השרת של הכלי לאיסוף נתונים

שלב 3: הפעלת mTLS ב-traceConfig

החלפת המפתח או האישור של הלקוח

קריטריוני דגימה

כותרת של הקשר למעקב של W3C

קדימות של כותרת על פני הגדרה מקומית

השבתת התיעוד

שינויים בהגדרות של כל שרת proxy

ההשפעה של תדירות הדגימה על הביצועים

שיקולי ביצועים

הגדרת זמני ריצה של Apigee ל-Cloud Trace‏ (OpenCensus)

הגדרת זמן הריצה של Apigee ל-Cloud Trace

הגדרת זמן הריצה של Apigee Hybrid ל-Cloud Trace

הפעלת מעקב מבוזר (OpenCensus)

הפעלת מעקב מבוזר ב-Cloud Trace באמצעות OpenCensus

הפעלת מעקב מבוזר עבור Jaeger באמצעות OpenCensus

צפייה בהגדרות של מעקב מבוזר

עדכון ההגדרה של מעקב מבוזר

השבתת ההגדרה של מעקב מבוזר

שינוי הגדרות איתור של שרתי proxy ל-API

עדכון של ביטולי הגדרות מעקב

מחיקת שינויים בהגדרות המעקב

פתרון בעיות של מעקב מבוזר

הפעלת מעקב מבוזר

משתנים בטווח `RESP_SENT`

משתנים בטווח `PROXY_POST_RESP_SENT`

שלב 3: הפעלת mTLS ב-`traceConfig`