המדיניות בנושא רישום הודעות ביומן

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

המדיניות MessageLogging מאפשרת לכם לרשום ביומן הודעות בהתאמה אישית ב-Cloud Logging או ב-syslog. אפשר להשתמש במידע שבלוגים למשימות שונות, כמו איתור בעיות בסביבת זמן הריצה של ה-API.

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

יש שתי דרכים להשתמש במדיניות MessageLogging:

  • הרכיב <CloudLogging> מתעד הודעות ב-Cloud Logging. כדי להשתמש בשיטה הזו, צריך להפעיל את ממשקי Cloud Logging API בפרויקט בענן שלכם ב-Google Cloud. מידע נוסף על הפעלת ממשקי API בפרויקט ב-Google Cloud זמין במאמר הפעלה והשבתה של שירותים.
  • רכיב <Syslog> מתעד הודעות ב-Syslog, פרוטוקול סטנדרטי לשליחת יומן מערכת או הודעות אירועים לשרת ספציפי. כדי להשתמש בשיטה הזו, צריך שיהיה שרת syslog זמין. אם אין לכם, אתם יכולים להשתמש בשירותים ציבוריים לניהול יומנים, כמו Splunk,‏ Sumo Logic ו-Loggly. מידע נוסף זמין במאמר בנושא הגדרת שירותים לניהול יומנים של צד שלישי.

הערה: אי אפשר להשתמש גם ברכיב <CloudLogging> וגם ברכיב <Syslog> באותה מדיניות.

רכיב <MessageLogging>

הגדרה של מדיניות <MessageLogging>.

ערך ברירת המחדל מידע נוסף מופיע בכרטיסייה מדיניות ברירת המחדל שבהמשך
חובה? חובה
סוג סוג
רכיב הורה לא רלוונטי
רכיבי צאצא <CloudLogging>
<Syslog>
<logLevel>

רכיב <MessageLogging> משתמש בתחביר הבא:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1">
    <DisplayName>Message Logging-1</DisplayName>
    <Syslog>
<!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. -->
        <Message>Some message for syslog</Message>
        <Host>localhost</Host>
        <Port>514</Port>
    </Syslog>
    <CloudLogging>
<!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. -->
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>api</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

לרכיב הזה יש את המאפיינים הבאים שמשותפים לכל המדיניות:

מאפיין ברירת מחדל חובה? תיאור
name לא רלוונטי חובה

השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים.

אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.
continueOnError FALSE אופציונלי מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המקרים. הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מאמרים קשורים:
enabled TRUE אופציונלי מגדירים את המדיניות למצב true כדי לאכוף אותה. מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.
async   FALSE הוצא משימוש המאפיין הזה הוצא משימוש.

בטבלה הבאה מופיע תיאור כללי של רכיבי הצאצא של <MessageLogging>:

שם השדה תיאור השדה
CloudLogging

הגדרת רישום הודעות ב-Cloud Logging.
Syslog

הגדרת ההודעות כך שיירשמו ביומן ב-syslog.

דוגמאות

CloudLogging

<MessageLogging name="LogToCloudLogging">
    <CloudLogging>
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>api</ResourceType>
    </CloudLogging>
</MessageLogging>

בדוגמה הזו מוצג שימוש ב תבניות של הודעות. ‫Since the Message element contains the flow variables

{"{message.queryparam.key}": "{message.queryparam.value}"}

כשמישהו מתקשר לשרת ה-proxy עם הערכים message.queryparam.key = "fruit" ו- message.queryparam.value = "apple", רשומת היומן שתתקבל תהיה {"fruit": "apple"}.

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>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

בדוגמה הזו, נניח שאתם צריכים לרשום ביומן מידע על כל הודעת בקשה שממשק ה-API מקבל מאפליקציות צרכניות. הערך 3f509b58 מייצג ערך מפתח ספציפי לשירות loggly. אם יש לכם חשבון Loggly, מחליפים את מפתח Loggly. הודעת היומן שנוצרת תאוכלס בארבעה ערכים: הארגון, ה-API proxy ושם הסביבה שמשויכים לעסקה, יחד עם הערך של פרמטר שאילתה בהודעת הבקשה. הפורמט של חותמות הזמן יהיה דומה ל-230704-13:42:17.376, בהתאם לפורמט שצוין ברכיב DateFormat.

Syslog over TLS/SSL

<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>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

אתם יכולים לשלוח הודעות לספקי רישום הודעות של צד שלישי באמצעות TLS/SSL על ידי הוספת הבלוק <SSLInfo>.

הפניה לרכיב צאצא

בקטעים הבאים מתוארים רכיבי הצאצא של <MessageLogging>.

<CloudLogging>

משתמשים ברכיב <CloudLogging> כדי לרשום הודעות ביומן ב-Cloud Logging.

שם השדה חובה? תיאור
LogName כן שם היומן. שם היומן צריך להיות בפורמט projects/{PROJECT_ID}/logs/{LOG_ID}. אפשר להשתמש במשתנים במקום ב-{PROJECT_ID} וב-{LOG_ID}.
Message כן

ההודעה שרוצים לרשום ביומן. להודעה יש מאפיין contentType, שהערך שלו יכול להיות text/plain או application/json עבור הודעות טקסט ו-JSON בהתאמה. דוגמאות
Label לא תווית לצירוף להודעה ביומן, אם יש. הם יהיו בפורמט של צמד מפתח/ערך כמו בדוגמה הבאה: 
<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>
ResourceType לא (ברירת המחדל היא כללית) מייצג את המשאב במעקב שמייצר את היומנים.

אימות ב-Cloud Logging

כדי להשתמש ברכיב <CloudLogging>, צריך לפרוס את ה-proxy ל-API כדי להשתמש באימות של Google. ‫Apigee ישתמש בפרטי כניסה שמתאימים לזהות של חשבון השירות שציינתם בבקשות היוצאות ל-Cloud Logging. לפרטים נוספים, ראו שימוש באימות של Google.

לחשבון השירות שמצורף ל-proxy ל-API בזמן הפריסה צריך להיות תפקיד עם ההרשאה logging.logEntries.create. אלא אם אתם צריכים שליטה מדויקת יותר, מומלץ להשתמש בתפקיד המוגדר מראש roles/logging.logWriter לחשבון השירות. למידע נוסף על תפקידים בניהול זהויות והרשאות גישה (IAM) ב-<CloudLogging>, אפשר לעיין במדריך בקרת הגישה.

פריסת שרת proxy ב-Apigee Hybrid

אם אתם משתמשים ב-Apigee hybrid, חשבון השירות של זמן הריצה שאתם יוצרים עבור Apigee hybrid צריך להתחזות לחשבון השירות של ה-proxy כדי לבצע קריאות מאומתות בשמו. לכן, לחשבון השירות של זמן הריצה של Apigee hybrid צריך להיות התפקיד iam.serviceAccountTokenCreator בחשבון השירות של ה-proxy.

<Syslog>

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

שם השדה חובה? תיאור השדה
Message כן

ההודעה שרוצים לרשום ביומן. להודעה יש מאפיין contentType, שהערך שלו יכול להיות text/plain או application/json עבור הודעות טקסט ו-JSON בהתאמה. דוגמאות
Host לא שם המארח או כתובת ה-IP של השרת שאליו צריך לשלוח את syslog. אם לא כוללים את הרכיב הזה, ברירת המחדל היא localhost.
Port לא היציאה שבה פועל syslog. אם לא כוללים את הרכיב הזה, ברירת המחדל היא 514.
Protocol לא ‫TCP או UDP (ברירת מחדל). פרוטוקול UDP הוא יעיל יותר, אבל פרוטוקול TCP מבטיח שהודעות יועברו לשרת syslog. לשליחת הודעות syslog ב-TLS/SSL, נתמך רק TCP.
FormatMessage לא, אבל נדרש <FormatMessage>true</FormatMessage> כדי להשתמש ב-Loggly.

‫true או false (ברירת מחדל)

האלמנט הזה מאפשר לכם לשלוט בפורמט של תוכן שנוצר על ידי Apigee ומוסף לפני ההודעה. אם המדיניות מוגדרת כ-True, לפני הודעת ה-syslog מתווסף מספר קבוע של תווים, שמאפשר לכם לסנן את המידע הזה מההודעות. דוגמה לפורמט הקבוע:

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee - - - Message starts here

המידע שנוצר על ידי Apigee כולל:

  • ‫<14> – ציון עדיפות (ראו Syslog Protocol) שמבוסס על רמת היומן ורמת המתקן של ההודעה.
  • ‫1 – הגרסה הנוכחית של syslog.
  • תאריך עם קיזוז ל-UTC‏ (UTC = +0000).
  • מזהה ייחודי אוניברסלי (UUID) של מעבד ההודעות.
  • ‫"Apigee - - - "

אם המדיניות מוגדרת כ-false (ברירת מחדל), התווים הקבועים האלה לא יתווספו בתחילת ההודעה.
PayloadOnly לא

‫true או false (ברירת מחדל)

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

אם לא כוללים את הרכיב הזה או משאירים אותו ריק, ערך ברירת המחדל הוא false.

FormatMessage
DateFormat לא

מחרוזת תבנית עיצוב שמשמשת לעיצוב חותמת הזמן של כל הודעת יומן. כברירת מחדל, Apigee משתמש ב-yyyy-MM-dd'T'HH:mm:ss.SSSZ. ההתנהגות של התבנית הזו מתוארת בתיעוד של המחלקות SimpleDateFormat של Java. לפי ההגדרה הזו, yyyy במחרוזת הפורמט יוחלף בשנה בת 4 ספרות, MM יוחלף במספר החודש בן 2 ספרות וכן הלאה.

SSLInfo לא

מאפשר לכם לרשום הודעות ביומן באמצעות SSL/TLS. שימוש עם רכיב המשנה <Enabled>true</Enabled>.

אם לא כוללים את הרכיב הזה או משאירים אותו ריק, ערך ברירת המחדל הוא false (ללא TLS/SSL).

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

אפשר להגדיר את התג <SSLInfo> באותו אופן שבו מגדירים אותו ב-TargetEndpoint, כולל הפעלת TLS/SSL דו-כיווני, כפי שמתואר בהפניה להגדרת proxy ל-API. יש תמיכה רק בפרוטוקול TCP.

<logLevel>

הערכים התקפים לרכיב <logLevel> הם: INFO (ברירת מחדל), ALERT, WARN, ERROR.

מגדירה רמה ספציפית של מידע שייכלל ביומן ההודעות.

אם משתמשים ברכיב FormatMessage (ומגדירים אותו כ-true), ההגדרה <logLevel> משפיעה על ציון העדיפות המחושב (המספר בתוך הסוגריים הזוויתיים) במידע שנוצר על ידי Apigee ומצורף בתחילת ההודעה.

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

כשמצרפים מדיניות MessageLogging לזרימת proxy ל-API, כדאי למקם אותה בתגובה של 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>

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

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

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

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

  • שימוש ב-<CloudLogging>: 
    steps.messagelogging.TooManyPendingLoggingRequest
  • שימוש ב-<Syslog>: 
    Log message size exceeded. Increase the max message size setting

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

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

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

מידע על הגדרת ניהול יומנים של צד שלישי זמין במאמרים הבאים:

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
steps.messagelogging.StepDefinitionExecutionFailed 500 See fault string.
steps.messagelogging.InvalidGoogleCloudLogName 500 This error is thrown when the LogName does not evaluate to the valid format of projects/{project}/logs/{logid}.
steps.messagelogging.InvalidJsonMessage 500 This error is thrown when the contentType attributes value has been chosen as application/json but the actual message value is not a valid JSON string,
steps.messagelogging.TooManyPendingLoggingRequest 500 This error is thrown when there are more than 2500 pending requests that are yet to be written to Cloud Logging. The 2500 limit is for each Apigee runtime pod. For example, if the traffic is distributed over two instances of Apigee runtime pods, the effective limit is 5000 requests.
-

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidProtocol The deployment of the MessageLogging policy can fail with this error if the protocol specified within the <Protocol> element is not valid. The valid protocols are TCP and UDP. For sending syslog messages over TLS/SSL, only TCP is supported.
InvalidPort The deployment of the MessageLogging policy can fail with this error if the port number is not specified within the <Port> element or if it is not valid. The port number must be an integer greater than zero.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. messagelogging.ML-LogMessages.failed = true

Example error response

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

Example fault rule

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

משתני Flow

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

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

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