מדיניות TraceCapture

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

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

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

גרסת טרום-השקה

השימוש במוצר הזה או בתכונה הזו כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, שמפורטים בחלק "תנאים כלליים לשירות" של התנאים הספציפיים לשירות. השימוש בתכונות ובמוצרים בגרסת טרום-GA הוא "כפי שהם" (As is), ויכול להיות שהתמיכה בהם תהיה מוגבלת. אתם יכולים לקרוא מידע נוסף בקטע תיאור שלבי ההשקה.

מדיניות 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 מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מאמרים קשורים: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי
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>

הערה:

• אי אפשר לעקוב אחרי משתני private ו-policy.secret.
• מומלץ להגדיר ב-Cloud Trace עד 15 משתנים, וב-Jaeger עד 25 משתנים.

<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.

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

<IgnoreUnresolvedVariables>

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

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

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

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

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

תחביר

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

דוגמה

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

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

הערה: ערך ברירת המחדל של הרכיב הוא false.

<ThrowExceptionOnLimit>

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

• אם המדיניות מוגדרת לערך true, המדיניות מחזירה שגיאה אם גודל המשתנה חורג מהמגבלה.
• אם המדיניות מוגדרת לערך false, המשתנה שחורג מהמגבלה ייחתך. המשתנה קוצץ לגודל המגבלה.

הערה: ערך ברירת המחדל של הרכיב הוא 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

מידע נוסף על שגיאות שקשורות למדיניות