אנטי-תבנית: הפעלה של מדיניות MessageLogging כמה פעמים ב-proxy ל-API

אתם צופים במסמכי התיעוד של Apigee ושל Apigee Hybrid.
לעיון במסמכי התיעוד של Apigee Edge.

המדיניות MessageLogging של Apigee מאפשרת למפתחים של API Proxy לרשום הודעות בהתאמה אישית ביומנים של Cloud Logging או בנקודות קצה של syslog. אפשר לרשום ביומן כל מידע חשוב שקשור לבקשת ה-API, כמו פרמטרי קלט, מטען ייעודי לבקשה, קוד תגובה, הודעות שגיאה (אם יש) וכן הלאה, כדי שיהיה אפשר לעיין בו בהמשך או להשתמש בו לניפוי באגים. המדיניות משתמשת בתהליך ברקע כדי לבצע את הרישום ביומן, אבל יש כמה דברים שחשוב לדעת לגבי השימוש במדיניות.

תבנית אנטי

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

נשתמש בדוגמה של API Proxy כדי להסביר את זה.

API מסוג proxy

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

בנוסף, יש מדיניות MessageLogging בשם LogErrorInfo שמופעלת רק אם יש שגיאה במהלך ההרצה של proxy ל-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 over TCP. אם משתמשים ביותר ממדיניות אחת כזו באותו proxy ל-API, התקורה של יצירה וניהול של חיבורי TLS תתפוס זיכרון מערכת נוסף ומחזורי מעבד (CPU) נוספים, מה שיוביל לבעיה בביצועים בהיקף גדול. השפעות שליליות דומות מתרחשות אם משתמשים ב-MessageLogging כדי להתחבר לנקודות קצה של Cloud Logging.

המדיניות 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 Proxy.
  • אם שרת ה-syslog איטי או לא יכול להתמודד עם נפח גדול של נתונים שנוצר על ידי מספר קריאות ל-syslog, זה יגרום לעומס על מעבד ההודעות, וכתוצאה מכך לעיבוד איטי של הבקשות ולזמן אחזור ארוך או לשגיאות מסוג 504 Gateway Timeout.

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

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

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

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

שיטה מומלצת

  • בתוך זרימת ה-proxy, משתמשים במופע אחד או יותר של המדיניות ExtractVariables או של המדיניות JavaScript כדי להגדיר את כל משתני הזרימה שיירשמו במשתנה הקשר. כך הם יהיו זמינים למדיניות MessageLogging שתופעל מאוחר יותר.
  • משתמשים במדיניות MessageLogging אחת כדי לרשום ביומן את כל הנתונים הנדרשים ב-PostClientFlow, שמופעל ללא תנאי.
  • אם אתם משתמשים ב-syslog, השתמשו בפרוטוקול UDP אם לא נדרשת מסירה מובטחת של הודעות לשרת syslog ואין חובה להשתמש ב-TLS/SSL.

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

דוגמה להפעלת MessageLogging Policy ב-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 אחרי Error Flow, חשוב להגדיר במפורש את המשתנים woeid ו-weather.response* באמצעות ExtractVariables או מדיניות JavaScript.

קריאה נוספת