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

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

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

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

מבוא

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

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

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

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

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

  • בקשה
    • שרת proxy
      • Preflow
      • PostFlow
    • יעד
      • Preflow
      • PostFlow
  • תשובה
    • שרת proxy
      • Preflow
      • PostFlow
    • יעד
      • Preflow
      • PostFlow

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

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

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

  • ‫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 נשלחות למעקב. מידע נוסף זמין במאמר בנושא שיקולים לגבי ביצועים.

הגדרת סביבות זמן ריצה של 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 מופעל:

  1. במסוף Google Cloud, עוברים אל APIs and Services:

    כניסה אל APIs and Services

  2. לוחצים על Enable APIs and Services.
  3. בסרגל החיפוש, מזינים Trace API.
  4. אם מוצג 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 עם סביבת זמן ריצה היברידית. כדי להוסיף את חשבון השירות, יחד עם התפקידים והמפתחות הנדרשים, מבצעים את השלבים הבאים:

  1. יוצרים חשבון שירות חדש: 
    gcloud iam service-accounts create \
    apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
    --project PROJECT_ID
  2. מוסיפים מדיניות 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
  3. יוצרים מַפְתח לחשבון השירות: 
    gcloud iam service-accounts keys \
    create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com
  4. מוסיפים את חשבון השירות לקובץ overrides.yaml.
    5. envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json
  5. כדי להחיל את השינויים על זמן הריצה, משתמשים ב-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 Trace

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

  1. מריצים את הקריאה הזו ל-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 נשלחות למעקב מבוזר. למידע נוסף על הגדרת 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 נשלחות למעקב מבוזר.
  • הפרמטר 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.

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

בדוגמה הבאה מוצג איך להשבית מעקב מבוזר שהוגדר ל-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, כל פרוקסי ה-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, פועלים לפי השלבים הבאים:

  1. משתמשים בפקודה הבאה כדי לאחזר שינויים קיימים בהגדרות המעקב: 
    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
      }
    }
  ]
}
  2. כדי לעדכן את ה-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, מבצעים את השלבים הבאים:

  1. משתמשים בפקודה הבאה כדי לאחזר שינויים קיימים בהגדרות המעקב: 
    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
      }
    }
  ]
}
  2. כדי למחוק את ה-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. ההשפעה יכולה לגרום לשימוש מוגבר בזיכרון, לדרישות גבוהות יותר של מעבד (CPU) ולזמן אחזור ארוך יותר. עוצמת ההשפעה תלויה בחלקה במורכבות של proxy ל-API (לדוגמה, מספר המדיניות) ובשיעור הדגימה ההסתברותית (מוגדר כ-samplingRate). ככל ששיעור הדגימה גבוה יותר, כך ההשפעה על הביצועים גבוהה יותר. למרות שההשפעה על הביצועים תלויה במספר גורמים, אפשר לצפות לירידה של 10-20% בביצועים כשמשתמשים במעקב מבוזר.

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