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

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

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

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

מבוא

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

כלי המעקב ב-Apigee Edge וכלי הניפוי באגים ב-Apigee שימושיים לפתרון בעיות ולמעקב אחרי שרתי proxy של API. עם זאת, הכלים האלה לא שולחים נתונים לשרתים של מעקב מבוזר כמו Cloud Trace או Jaeger. כדי לראות נתונים של זמן הריצה של Apigee בדוח מעקב מבוזר, צריך להפעיל במפורש את המעקב המבוזר בזמן הריצה של Apigee. אחרי שמפעילים את האפשרות 'מעקב', זמן הריצה יכול לשלוח נתוני מעקב לשרתי מעקב מבוזרים ולהשתתף במעקב קיים. כתוצאה מכך, תוכלו לראות נתונים מתוך המערכת האקולוגית של Apigee ומחוצה לה במקום אחד.

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

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

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

בקשה
- Proxy
  - Preflow
  - PostFlow
- יעד
  - Preflow
  - PostFlow
תגובה
- Proxy
  - Preflow
  - PostFlow
- יעד
  - Preflow
  - PostFlow

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

קריאה נכנסת ל-API ב-Apigee עשויה להכיל כותרות מעקב, מכיוון שהקריאה היא חלק ממעקב קיים. במקרה הזה, Apigee משתתף במעקב הקיים ומעביר את הכותרות לקריאה היוצאת ל-API. סביבת זמן הריצה של Apigee מבינה את הפורמט של הכותרת Zipkin B3. לכן, הוא מזהה את הכותרות x-b3-traceid, x-b3-spanid ו-x-b3-sampled כשמשתתפים במעקב קיים. עם זאת, אם אין כותרות מעקב בקריאה נכנסת ל-API, ‏ Apigee יוסיף את כותרות המעקב שלו ויפיץ אותן לקריאה היוצאת ל-API. שירותים אחרים יכולים לגשת לכותרות ולהשתתף במעקב אם נדרש.

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

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

‫POST_RESP_SENT: יחידה לוגית למעקב זו מתווספת אחרי שמתקבלת תגובה משרת היעד.
‫POST_CLIENT_RESP_SENT: יחידה לוגית למעקב זו מתווספת אחרי שתשובת ה-proxy נשלחת ללקוח.

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

המשתנים הבאים גלויים בטווח POST_RESP_SENT:

REQUEST_URL (request.url)
REQUEST_VERB (request.verb)
קוד סטטוס התגובה (response.status.code)
ROUTE_NAME (route.name)
ROUTE_TARGET (route.target)
TARGET_BASE_PATH (target.basepath)
TARGET_HOST (target.host)
TARGET_IP (target.ip)
TARGET_NAME (target.name)
TARGET_PORT (target.port)
TARGET_RECEIVED_END_TIMESTAMP (target.received.end.timestamp)
TARGET_RECEIVED_START_TIMESTAMP (target.received.start.timestamp)
TARGET_SENT_END_TIMESTAMP (target.sent.end.timestamp)
TARGET_SENT_START_TIMESTAMP (target.sent.start.timestamp)
TARGET_SSL_ENABLED (target.ssl.enabled)
TARGET_URL (target.url)

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

המשתנים הבאים גלויים בטווח POST_CLIENT_RESP_SENT:

‫API_PROXY_REVISION (apiproxy.revision)
APIPROXY_NAME (apiproxy.name)
‫CLIENT_RECEIVED_END_TIMESTAMP (client.received.end.timestamp)
‫CLIENT_RECEIVED_START_TIMESTAMP (client.received.start.timestamp)
CLIENT_SENT_END_TIMESTAMP (client.sent.end.timestamp)
CLIENT_SENT_START_TIMESTAMP (client.sent.start.timestamp)
ENVIRONMENT_NAME (environment.name)
‫FAULT_SOURCE (message.header + InternalHeaders.FAULT_SOURCE)
IS_ERROR (is.error)
MESSAGE_ID (message.id)
MESSAGE_STATUS_CODE (message.status.code)
PROXY_BASE_PATH (proxy.basepath)
PROXY_CLIENT_IP (proxy.client.ip)
PROXY_NAME (proxy.name)
PROXY_PATH_SUFFIX (proxy.pathsuffix)
PROXY_URL (proxy.url)

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

סביבת זמן הריצה של Apigee תומכת במערכות הבאות של מעקב מבוזר:

Cloud Trace
Jaeger

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

מעקב אחרי כל הקריאות ל-API בזמן הריצה של Apigee ישפיע על הביצועים, ולכן Apigee מאפשרת להגדיר שיעור דגימה הסתברותי. באמצעות שיעור הדגימה, אפשר לציין את מספר הקריאות ל-API שנשלחות למעקב מבוזר. לדוגמה, אם מציינים את שיעור הדגימה כ-0.4, המשמעות היא ש-40% מהקריאות ל-API נשלחות למעקב. מידע נוסף זמין במאמר בנושא שיקולי ביצועים.

שיעור הדגימה המקסימלי שאפשר להגדיר הוא 0.5.

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

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

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

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

כדי לוודא ש-Cloud Trace API מופעל:

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

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

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

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

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

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

יוצרים מַפְתח לחשבון השירות:
```
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

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

לפני שמפעילים מעקב מבוזר ב-Cloud Trace או ב-Jaeger, צריך ליצור את משתני הסביבה הבאים:

TOKEN="Authorization: Bearer $(gcloud auth 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.

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

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

מריצים את הקריאה הזו ל-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}}'
```
גוף הבקשה בדוגמה מורכב מהרכיבים הבאים:
- הערך של samplingRate מוגדר כ-0.1. המשמעות היא שכ-10% מהקריאות ל-API נשלחות ל-distributed tracing. מידע נוסף על הגדרת samplingRate לסביבת זמן הריצה זמין במאמר שיקולים בנוגע לביצועים.
- הפרמטר exporter מוגדר לערך CLOUD_TRACE.
- נקודת הקצה מוגדרת לפרויקט בענן של Google שאליו רוצים לשלוח את המעקב. הערה: הערך הזה חייב להיות זהה לחשבון השירות שהוגדר בשלב ההגדרה.
תגובה מוצלחת תיראה כך:
```
{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}
```

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

בדוגמה הבאה אפשר לראות איך מפעילים את התכונה 'מעקב מבוזר' ב-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"
    }'

בדוגמה הזו:

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

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

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

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

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

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

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

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

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

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

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

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

‫

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

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

כדי לעדכן את ההגדרה של 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 '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

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

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "OFF",
    "samplingRate": 0.1
  }
}

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

כשמפעילים מעקב מבוזר בסביבת זמן הריצה של Apigee, כל שרתי ה-proxy של ה-API בסביבת זמן הריצה משתמשים באותה הגדרה למעקב. עם זאת, אפשר לשנות את ההגדרה של מעקב מבוזר עבור שרת 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 \
```

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

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

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

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

מבוא

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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