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

אתם צופים במסמכי העזרה של Apigee Edge.
כניסה למסמכי העזרה של Apigee X. info

מה

אחת הדרכים הטובות ביותר לאתר בעיות בסביבת זמן הריצה של ה-API היא לתעד הודעות ביומן. אפשר לצרף ולקבוע מדיניות של MessageLogging ב-API כדי לתעד הודעות בהתאמה אישית בדיסק מקומי (Edge לענן פרטי בלבד) או ב-syslog.

דוגמאות

<MessageLogging name="LogToSyslog">
  <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>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <DateFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

<MessageLogging name="LogToSyslog">
  <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>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

הפניה לרכיב

משתמשים ברכיבים הבאים כדי להגדיר את סוג המדיניות של MessageLogging.

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

סכימות

הערות לגבי שימוש

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

האירוע PostClientFlow הוא אירוע מיוחד בשתי דרכים:

1. הוא בוצע רק כחלק מתהליך התגובה.
2. זהו התהליך היחיד שמתבצע אחרי ששרת ה-proxy נכנס למצב שגיאה.

מכיוון שהיא מתבצעת ללא קשר להצלחה או לכישלון של שרת ה-proxy, אפשר להוסיף מדיניות של MessageLogging ל-PostClientFlow ולדעת שהיא תמיד תתבצע.

בתמונה הבאה של Trace מוצגת מדיניות של MessageLogging שפועלת כחלק מ-PostClientFlow, אחרי שהכלל DefaultFaultRule פועל:

בדוגמה הזו, המדיניות של אימות מפתח ה-API גרמה לשגיאה בגלל מפתח לא תקין.

בהמשך מוצגת ההגדרה של ProxyEndpoint שכוללת את PostClientFlow:

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

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

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

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

Log message size exceeded. Increase the max message size setting

אם נתקלתם בבעיה הזו ב-Edge for Private Cloud בגרסה 4.15.07 ואילך, עליכם לאתר את הקובץ message-logging.properties ולהשתמש בפתרון הבא:

מגדילים את המאפיין max.log.message.size.in.kb (ערך ברירת המחדל = 128KB) בקובץ message-logging.properties.

ב-Edge for Private Cloud בגרסה 4.16.01 ואילך, מגדירים את המאפיין conf/message-logging.properties+max. log.message.size.in.kb בקובץ /opt/apigee/customer/application/message-processor.properties ומפעילים מחדש את Message Processor. לתשומת ליבכם: כברירת מחדל, הנכס הזה מופיע בתחילה עם הערה.

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

שליטה בחותמת הזמן של הודעות ביומן ב-Edge for Private Cloud

כברירת מחדל, חותמת הזמן בכל הודעות היומן היא בפורמט:

yyyy-MM-dd'T'HH:mm:ss.SSSZ

אפשר לשנות את ברירת המחדל הזו ברמת המערכת עבור יעדים של syslog באמצעות הרכיב DateFormat. ההתנהגות של התבנית הזו מתוארת במסמכי התיעוד של הקלאס SimpleDateFormat של Java. בהתאם להגדרה הזו, הערך yyyy יוחלף בשנה בת 4 ספרות, הערך MM יוחלף במספר חודש בן 2 ספרות וכן הלאה. הפורמט שלמעלה עשוי להוביל למחרוזת מהצורה הבאה:

2022-09-28T22:38:11.721+0000

אפשר להשתמש במאפיין conf_system_apigee.syslogger.dateFormat במעבד ההודעות של Edge כדי לקבוע את הפורמט. לדוגמה, שינוי הפורמט של ההודעה ל:

yy/MM/dd'T'HH:mm:ss.SSSZ

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

22/09/28T22:38:11.721+0000

כדי לשנות את הפורמט:

1. פותחים את הקובץ message-processor.properties בכלי לעריכה. אם הקובץ לא קיים, יוצרים אותו:
   > vi /opt/apigee/customer/application/message-processor.properties
2. מגדירים את המאפיינים לפי הצורך:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. שומרים את השינויים.
4. מוודאים שהבעלים של קובץ המאפיינים הוא המשתמש 'apigee':
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. מפעילים מחדש את Edge Message Processor:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

המיקום של קובץ היומן ב-Edge for Private Cloud

Edge for Private Cloud מגרסה 4.16.01 ואילך

כברירת מחדל, יומני ההודעות של Private Cloud נמצאים בספרייה הבאה בצמתים של Message Processor:

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

כדי לשנות את מיקום ברירת המחדל של היומן, משנים את המאפיינים בקובץ message-logging.properties במעבדי ההודעות:

• bin_setenv_data_dir – הגדרת נתיב הבסיס לאחסון קובצי יומנים. לדוגמה, bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir – אם מגדירים את הערך הזה לנתיב יחסי, למשל conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.
  
  אם מגדירים את הערך הזה לנתיב מוחלט, למשל conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, יומני ההודעות יישמרו ב-/opt/apigee/var/log/messages/messagelog/. נתיב מוחלט מקבל עדיפות על פני bin_setenv_data_dir.
  
  שימו לב שצריך להפנות לנכס בתור conf/message-logging.properties+log.root.dir כי הוא מופיע בסוגריים מרובעים כברירת מחדל. מידע נוסף זמין במאמר הגדרת אסימון שמנוטרל כרגע באמצעות תגובה.

אם רוצים לאחסן את קובצי היומן במבנה קובץ שטוח, כך שכל קובצי היומן ימוקמו באותה ספרייה, צריך להגדיר את הערך true למאפיין conf/message-logging.properties+enable.flat.directory.structure בקובץ message-logging.properties. ההודעות מאוחסנות בספרייה שצוינה במאפיינים שלמעלה, ושמות הקבצים הם מסוג {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

כדי להגדיר את המאפיינים האלה:

1. פותחים את הקובץ message-processor.properties בכלי לעריכה. אם הקובץ לא קיים, יוצרים אותו:
   > vi /opt/apigee/customer/application/message-processor.properties
2. מגדירים את המאפיינים לפי הצורך:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. שומרים את השינויים.
4. מוודאים שהבעלים של קובץ המאפיינים הוא המשתמש 'apigee':
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. מפעילים מחדש את רכיב Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge for Private Cloud 4.15.07 וגרסאות מוקדמות יותר

כברירת מחדל, יומני ההודעות נמצאים במיקום הבא במעבדי ההודעות:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

כדי לשנות את מיקום ברירת המחדל של היומן, משנים את המאפיינים הבאים בקובץ message-logging.properties במעבדי ההודעות:

• data.dir – מגדיר את נתיב הבסיס לאחסון קובצי היומנים. לדוגמה, data.dir=‎/opt/apigee4/var/log
• log.root.dir – אם מגדירים את הערך הזה לנתיב יחסי, למשל log.root.dir=custom/folder/, הנתיב מצורף למיקום data.dir.

לדוגמה, השילוב של שני המאפיינים יגדיר את ספריית הרישום ב-‎/opt/apigee4/var/log/custom/folder/messagelog/‎ (שימו לב ש-‎ /messagelog מתווסף באופן אוטומטי).

אם מגדירים את הפרמטר הזה לנתיב מוחלט, למשל log.root.dir=/opt/apigee4/var/log/messages, יומני ההודעות יישמרו בנתיב /opt/apigee4/var/log/messages/messagelog/. נתיב מוחלט ב-log.root.dir מקבל עדיפות על פני data.dir.

אם רוצים לאחסן קובצי יומן במבנה קובץ שטוח, כך שכל קובצי היומן ימוקמו באותה ספרייה, צריך להגדיר את הערך enable.flat.directory.structure כ-true בקובץ message-logging.properties במעבדי ההודעות. ההודעות מאוחסנות בספרייה שצוינה בנכסים שלמעלה, ושמות הקבצים הם בפורמט {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

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

אפשר לציין ערכי ברירת מחדל לכל משתנה בתבנית ההודעה בנפרד. לדוגמה, אם אי אפשר לפתור את המשתנה request.header.id, הערך שלו יוחלף בערך unknown.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

אפשר לציין ערך ברירת מחדל משותף לכל המשתנים שלא נפתרו על ידי הגדרת המאפיין defaultVariableValue ברכיב Message:

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

הגדרת שירותי ניהול יומנים של צד שלישי

המדיניות של MessageLogging מאפשרת לשלוח הודעות syslog לשירותי ניהול יומנים של צד שלישי, כמו Splunk,‏ Sumo Logic ו-Loggly. אם רוצים לשלוח syslog לאחד מהשירותים האלה, צריך לעיין במסמכי התיעוד של השירות כדי להגדיר את המארח, היציאה והפרוטוקול של השירות, ואז להגדיר את רכיב ה-Syslog במדיניות הזו בהתאם.

במסמכים הבאים מוסבר איך מגדירים ניהול יומנים של צד שלישי:

• Splunk (בוחרים את גרסת המוצר)
  כדאי לעיין גם בפוסט הזה בקהילה של Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Sumo Logic
  • מומלץ גם לעיין בפוסט הזה בקהילה של Apigee: https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • דוגמה מלאה לשימוש ב-Sumo Logic כשירות הרישום ביומן מופיעה בפוסט הבא בקהילה של Apigee. הפתרון משתמש במדיניות JavaScript אחת כדי לשלוח בקשות HTTP POST אל Sumo Logic HTTP Source Collector: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  כשמשתמשים ב-Loggly, צריך להוסיף את <FormatMessage>true</FormatMessage> למדיניות כצאצא של האלמנט <Syslog>.
  מידע נוסף על רישום הודעות ביומן ב-Loggly זמין גם בפוסט הזה בקהילה של Apigee: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

מסמך עזרה בנושא שגיאות

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

שגיאות זמן ריצה

השגיאות האלה עשויות להתרחש כשהמדיניות מופעלת.

שגיאות פריסה

השגיאות האלו עשויות להתרחש כאשר פורסים שרת proxy שמכיל את המדיניות הזו.

משתני כשל

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

דוגמה לתגובת שגיאה

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

דוגמה לכלל שגוי

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>

משתני זרימה

המשתנים הבאים מאוכלסים כשיש כשל במדיניות.

• messagelogging.failed
• messagelogging.{stepdefinition-name}.failed

נושאים קשורים

• משתנים שנחשפים על ידי Edge: הפניה למשתנים