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

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

מה

אחת הדרכים הטובות ביותר לאתר בעיות בסביבת זמן הריצה של ה-API היא לרשום הודעות. אפשר לצרף מדיניות MessageLogging ולהגדיר אותה ב-API כדי לרשום הודעות מותאמות אישית בדיסק מקומי (Edge for Private Cloud בלבד) או ב-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.

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

סכימות

הערות שימוש

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

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

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

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

תמונת המעקב הבאה מציגה מדיניות 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_max.log.message.size.in.kb בקובץ /opt/apigee/customer/application/message-processor.properties ולהפעיל מחדש את מעבד ההודעות.

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

שליטה בחותמת הזמן של הודעות היומן ב-Edge לענן פרטי

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

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:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor

רישום מיקום של קבצים ב-Edge לענן פרטי

Edge for Private Cloud 4.16.01 ואילך

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

/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 כי היא מסומנת כברירת מחדל עם הערות. למידע נוסף, אפשר לקרוא את המאמר הגדרת אסימון שמקבל תגובה כרגע.

כדי לאחסן קובצי יומן במבנה שטוח כדי שכל קובצי היומן ישויכו לאותה ספרייה, צריך להגדיר את הערך conf/message-logging.properties+enable.flat.directory.structure כ-true בקובץ 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 מחדש

Edge לענן פרטי מגרסה 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>.
  בנוסף, כדאי לעיין בפוסט הזה של קהילת Apigee למידע נוסף על התחברות הודעות ל-Loggly: 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: הפניה למשתנים