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

אתם צופים במסמכי התיעוד של 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.

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

<FileName>mylog.log</FileName>

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

סכימות

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

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

ל-PostClientFlow יש שני מאפיינים מיוחדים:

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

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

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

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

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

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

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

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

יכול להיות שיהיו עיכובים בקבלת הודעות יומן שנשלחות לנקודת קצה חדשה של syslog. הסיבה לכך היא התנהגות מכוונת של 'הפעלה במצב התחלתי' במדיניות. כשמגדירים יעד חדש לרישום ביומן, בנוסף ליעדים הקיימים, מעבד ההודעות (MP) עשוי להוסיף לתור 1,000 הודעות יומן בזיכרון לפני שהוא שולח אותן. בסביבות עם נפח תנועה נמוך, יכול להיות שיהיה עיכוב ראשוני. העיכוב הראשוני הזה לא מורגש בעומסי עבודה רגילים של ייצור, כי ההודעות מצטברות במהירות. אחרי שמגיעים לסף, הודעות היומן יימסרו כמצופה. ביצוע הפעלה מחדש מסודרת של מעבד ההודעות יכול גם להפעיל את המסירה של הודעות בתור, כשהן יוצאות מהתור.

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

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

הערה: אי אפשר לגשת למשתני הודעת התגובה ב-Edge מתוך Error Flow. המשתנים האלה לא זמינים גם ב-PostClientFlow אם הזרימה הקודמת הייתה Error Flow. אם רוצים לרשום ביומן מידע על תגובות מ-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

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

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

אם רוצים לאחסן קובצי יומן במבנה קבצים שטוח, כך שכל קובצי היומן ימוקמו באותה ספרייה, צריך להגדיר את 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 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: Log messages into Splunk
• Sumo Logic
  • אפשר גם לעיין בפוסט הזה בקהילת Apigee: Setting up logging with Sumo Logic, which host should I use?
  • דוגמה מלאה לשימוש ב-Sumo Logic כשירות רישום ביומן זמינה בפוסט הבא בקהילת Apigee. הפתרון משתמש במדיניות JavaScript אחת כדי לשלוח בקשות HTTP POST אל Sumo Logic HTTP Source Collector: Logging to Sumo Logic using JavaScript and HTTP
• ‫Loggly
  כשמשתמשים ב-Loggly, נדרש <FormatMessage>true</FormatMessage> במדיניות כצאצא של האלמנט <Syslog>.
  מידע נוסף על רישום הודעות ב-Loggly זמין גם בפוסט הזה בקהילת Apigee: רישום הודעות ב-Loggly

הפניה לשגיאה

בקטע הזה מתוארים קודי השגיאה והודעות השגיאה שהוחזרו, ומשתני התקלה שמוגדרים על ידי 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: הפניה למשתנים