מדיניות TraceCapture

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

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

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

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

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

<TraceCapture>

הגדרה של מדיניות TraceCapture.

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג סוג מורכב
רכיב אב לא רלוונטי
רכיבי צאצא <DisplayName>
<IgnoreUnresolvedVariables>
<ThrowExceptionOnLimit>
<Variables>

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

תחביר

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
    <Variables>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>
</TraceCapture>

דוגמה

בדוגמה הבאה מוצגת הגדרת המדיניות TraceCapture:

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>Distributed-Trace-Capture-Policy-1</DisplayName>
    <Variables>
        <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
        <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>
</TraceCapture>

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

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

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

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

בטבלה הבאה מפורטים רכיבי המשנה של <TraceCapture>:

רכיב צאצא חובה? תיאור
<DisplayName> אופציונלי מציין שם מותאם אישית למדיניות.
<Variables> אופציונלי מציינת את רשימת המשתנים למעקב.
<IgnoreUnresolvedVariables> אופציונלי המדיניות הזו קובעת אם העיבוד ייפסק כשנתקלים במשתנה שלא נפתר.
<ThrowExceptionOnLimit> אופציונלי המאפיין הזה מציין אם צריך לקטום משתנה אם הגודל שלו חורג מהמגבלה של 256 בייט.
רכיבי צאצא אחרים
<MergeBehavior> אופציונלי המדיניות קובעת את אופן המיזוג של הודעות התגובה.

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

בקטע הזה מתוארים רכיבי הבן של <TraceCapture>.

<DisplayName>

אפשר להשתמש במאפיין הזה בנוסף למאפיין name כדי לתת למדיניות שם אחר, שנשמע יותר טבעי, ב-UI של עורך ה-proxy לניהול.

הרכיב <DisplayName> משותף לכל סוגי המדיניות.

ערך ברירת המחדל לא רלוונטי
חובה? זה שינוי אופציונלי. אם לא מציינים את <DisplayName>, המערכת משתמשת בערך של מאפיין name של המדיניות.
סוג String
רכיב אב <PolicyElement>
רכיבי צאצא ללא

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

תחביר

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

דוגמה

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

לרכיב <DisplayName> אין מאפיינים או רכיבי צאצא.

<Variables>

מציינת את רשימת המשתנים למעקב.

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג סוג מורכב
רכיב אב <TraceCapture>
רכיבי צאצא <Variable>

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

תחביר

<Variables>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
</Variables>

דוגמה

בדוגמה הבאה מוצגים משתני הזרימה flow-variable-1 ו-flow-variable-2:

<Variables>
    <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
    <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
</Variables>

<Variable>

מציין את המשתנים שיוספו לנתוני המעקב.

ערך ברירת המחדל לא רלוונטי
חובה? חובה
סוג סוג מורכב
רכיב אב <Variables>
רכיבי צאצא ללא

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

תחביר
<Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
דוגמה

בדוגמה הבאה, משתנה המעקב trace-variable-1 מוגדר לערך של משתנה התהליך flow-variable-1:

<Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>

אם משתנה הזרימה flow-variable-1 לא זמין, הערך של trace-variable-1 מוגדר לערך ברירת המחדל default-val-1.

בטבלה הבאה מתוארים המאפיינים של <Variable>:

מאפיין חובה? סוג תיאור
name חובה String שם שאפשר להשתמש בו כדי להתייחס לנתונים שנאספו עבור המשתנה שצוין. השם הזה יוצג בדוח של מעקב מבוזר.
ref חובה String המשתנה שעבורו אתם אוספים את נתוני המעקב. המשתנה הזה יכול להיות משתנה של זרימה שהוגדר מראש על ידי Apigee או משתנה מותאם אישית ב-proxy ל-API.

<IgnoreUnresolvedVariables>

קובעת אם העיבוד ייפסק כשנתקלים במשתנה לא פתור.

ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג בוליאני
רכיב אב <TraceCapture>
רכיבי צאצא ללא

הערך true גורם למערכת להתעלם ממשתנים שלא נפתרו ולהמשיך בעיבוד. אחרת, הערך הוא false. ערך ברירת המחדל הוא true.

ההגדרה של <IgnoreUnresolvedVariables> ל-true שונה מההגדרה של <TraceCapture>'s continueOnError ל-true. אם מגדירים את continueOnError ל-true, מערכת Apigee מתעלמת מכל השגיאות, ולא רק משגיאות במשתנים.

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

תחביר

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

דוגמה

בדוגמה הבאה, הערך של <IgnoreUnresolvedVariables> מוגדר ל-false:

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

<ThrowExceptionOnLimit>

מציין את ההתנהגות של המדיניות כשהגודל של המשתנה חורג מהמגבלה של 256 בייטים.

  • אם המדיניות מוגדרת לערך true, היא מחזירה שגיאה אם גודל המשתנה חורג מהמגבלה.
  • אם המדיניות מוגדרת לערך false, המשתנה שחורג מהמגבלה יקוצר. המשתנה יקוצר לגודל המגבלה.
ערך ברירת המחדל לא רלוונטי
חובה? אופציונלי
סוג בוליאני
רכיב אב <TraceCapture>
רכיבי צאצא ללא

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

תחביר

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

דוגמה

בדוגמה הבאה, הערך של <ThrowExceptionOnLimit> מוגדר ל-true.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

קודי שגיאה

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

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

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

קוד תקלה סטטוס HTTP מטרה
steps.tracecapture.UnresolvedVariable 500

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

  • לא רלוונטי (לא זמין בתהליך הספציפי שבו המדיניות מופעלת)
    • או
  • אי אפשר לפתור (לא מוגדר)
steps.tracecapture.VariableValueLimitExceeded 500

השגיאה הזו מתרחשת אם הרכיב <ThrowExceptionOnLimit> מוגדר ל-true והגודל של משתנה כלשהו חורג מ-256 בייט.

משתני תקלות

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

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

בטבלה הבאה מתוארים משתני השגיאה שספציפיים למדיניות הזו.

משתנים כאשר: דוגמה
fault.name הערך fault.name יכול להתאים לכל אחת מהתקלות שמופיעות בטבלה שגיאות בזמן ריצה. שם התקלה הוא החלק האחרון של קוד התקלה. fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed ‫POLICY_NAME הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה. tracecapture.trace-capture-1.failed = true
מידע נוסף על שגיאות שקשורות למדיניות זמין במאמר מה צריך לדעת על שגיאות שקשורות למדיניות.