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

מוצג המסמך של 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 להיות בטוחים שהם תמיד יופעלו.

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

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

Log message size exceeded. Increase the max message size setting

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

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

עבור Edge ל-Private Cloud 4.16.01 ואילך, מגדירים את המאפיין conf/message-logging.properties+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

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

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

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

1. פותחים את הקובץ message-processor.properties ב עם הרשאת עריכה. אם הקובץ לא קיים, יוצרים אותו:
   > וי /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 ל-Private Cloud מגרסה 4.16.01 ואילך

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

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