Antipattern: יש להפעיל את מדיניות MessageLogging מספר פעמים בשרת proxy של API

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

מדיניות MessageLogging של Apigee Edge מאפשרת למפתחי שרת Proxy API לרשום הודעות מותאמות אישית ב-Syslog או בדיסק (Edge בענן פרטי בלבד). תוכלו לתעד פרטים חשובים שקשורים לבקשת ה-API, כמו פרמטרים של קלט, מטען ייעודי (payload), קוד תגובה, הודעות שגיאה (אם יש) וכו'. תוכלו גם לתעד את הפרטים האלה לצורך עיון במועד מאוחר יותר או לצורך ניפוי באגים. המדיניות מתבססת על תהליך רקע לביצוע הרישום ביומן, אבל יש אזהרות לגבי השימוש במדיניות.

דוגמת עיצוב

המדיניות MessageLogging מספקת דרך יעילה לקבל מידע נוסף על בקשת API ולנפות באגים אם נתקלים בבעיות בבקשת ה-API. עם זאת, לשימוש באותה מדיניות MessageLogging יותר מפעם אחת או שימוש בנתונים מרובים של מדיניות MessageLogging במקטעים באותו שרת proxy של API בתהליכים שאינם PostClientFlow, עלולים להיות השלכות שליליות. הסיבה לכך היא ש-Apigee Edge פותח חיבור לשרת Syslog חיצוני עבור מדיניות MessageLogging. אם המדיניות משתמשת ב-TLS באמצעות TCP, יש תקורה נוספת ביצירת חיבור TLS.

נסביר זאת בעזרת דוגמה לשרת proxy ל-API.

API מסוג proxy

בדוגמה הבאה, מדיניות MessageLogging בשם "LogRequestInfo" ממוקמת בתהליך הבקשה, ומדיניות MessageLogging אחרת בשם "LogResponseInfo" מתווספת לתהליך התגובה. שניהם נמצאים ב-ProxyEndpoint PreFlow. המדיניות LogRequestInfo מופעלת ברקע מיד לאחר ששרת ה-API של ה-API מקבל את הבקשה, והמדיניות LogResponseInfo מופעלת אחרי ששרת ה-Proxy מקבל תגובה משרת היעד, אך לפני ששרת ה-proxy מחזיר את התגובה ללקוח ה-API. הפעולה הזו תצרוך משאבי מערכת נוספים בזמן היצירה של שני חיבורי TLS.

בנוסף, קיימת מדיניות MessageLogging בשם "LogErrorInfo" שמופעלת רק אם יש שגיאה במהלך הביצוע של שרת ה-API של שרת ה-API.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ProxyEndpoint name="default">
  ...
<FaultRules>
    <FaultRule name="fault-logging">
        <Step>
            <Name>LogErrorInfo</Name>
        </Step>
    </FaultRule>
</FaultRules>
<PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>LogRequestInfo</Name>
      </Step>
    </Request>
  </PreFlow>
  <PreFlow name="PreFlow">
    <Response>
      <Step>
        <Name>LogResponseInfo</Name>
      </Step>
    </Response>
  </PreFlow>
  ...
</ProxyEndpoint>

המדיניות בנושא רישום הודעות

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

המדיניות של LogRequestInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogRequestInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

המדיניות של LogResponseInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogResponseInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Status: {response.status.code}, Response {response.content}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

המדיניות של LogErrorInfo

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogErrorInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Fault name: {fault.name}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>ERROR</logLevel>
</MessageLogging>

השפעה

  • תקורה מוגברת ברשת כתוצאה מיצירת חיבורים לשרתי היומנים מספר פעמים במהלך התהליך של שרת ה-API של שרת ה-API.
  • אם שרת ה-Syslog איטי או לא יכול לטפל בנפח הגבוה שנגרם עקב קריאות מרובות של Syslog, הדבר יגרום ללחץ חוזר על מעבד ההודעות, והתוצאה תהיה עיבוד בקשות איטי וזמן אחזור ארוך או שגיאות זמן קצוב לתפוגה של 504 Gateway.
  • מספר גדול יותר של מתארי קבצים בו-זמנית שנפתחו על ידי מעבד ההודעות בהגדרות של ענן פרטי שבו נעשה שימוש ברישום קבצים ביומן.

  • אם מדיניות MessageLogging מוצבת בזרימות שאינן זרימה של PostClient, ייתכן שהמידע לא יתועד, מכיוון שמדיניות MessageLogging לא תבוצע אם יתרחש כשל לפני הביצוע של המדיניות הזו.

    בדוגמה הקודמת של ProxyEndpoint, המידע לא יירשם בנסיבות הבאות:

    • אם מדיניות כלשהי שנוצרה לפני המדיניות LogRequestInfo בתהליך הבקשה נכשלת.
      או
    • אם שרת היעד נכשל ומוצגת שגיאה כלשהי (HTTP 4XX, 5XX). במצב כזה, אם לא מוחזרת תגובה מוצלחת, המדיניות LogResponseInfo לא תבוצע.

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

שיטה מומלצת

  • צריך להשתמש במדיניות extracts או במדיניות JavaScript כדי להגדיר את כל משתני התהליך לתיעוד, כך שיהיו זמינים במדיניות MessageLogging.
  • להשתמש במדיניות MessageLogging יחידה כדי לתעד את כל הנתונים הנדרשים ב-PostClientFlow, אשר מופעל ללא תנאי.
  • יש להשתמש בפרוטוקול UDP, שבו אין צורך בשליחה מובטחת של הודעות לשרת ה-Syslog, ולא חייבים להשתמש ב-TLS (אבטחת שכבת התעבורה) או ב-SSL.

מדיניות MessageLogging תוכננה להיות מופרדת מהפונקציונליות של ה-API בפועל, כולל טיפול בשגיאות. לכן, אם תפעילו את הפונקציה ב-PostClientFlow, שלא במסגרת עיבוד בקשה/תשובה, היא תמיד תרשום נתונים, גם אם ה-API נכשל או לא.

זוהי דוגמה שמפעילה מדיניות MessageLogging ב-PostClientFlow:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 ...
<PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>LogInfo</Name>
            </Step>
        </Response>
</PostClientFlow>
 ...

הנה דוגמה למדיניות MessageLogging, LogInfo, שמתעדת את כל הנתונים:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging name="LogInfo">
  <Syslog>
    <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {woeid} Status: {weather.response.code}, Response {weather.response}, Fault: {fault.name:None}.</Message>
    <Host>logs-01.loggly.com</Host>
    <Port>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>INFO</logLevel>
</MessageLogging>

משתני התגובות לא זמינים ב-PostClientFlow בעקבות זרימת השגיאה, ולכן חשוב להגדיר במפורש את המשתנים woeid ו-weather.response* באמצעות המדיניות extracts או המדיניות של JavaScript.

קריאה נוספת