תיעוד
=======

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

תיעוד הודעות
---------------

ניתן לתעד הודעות על ידי קריאה ל [Yii::log] או [Yii::trace]. ההבדל בין שני המתודות הללו היא שהמתודה השנייה מתעדת הודעה רק בזמן שהאפליקציה נמצאת במצב של [ניפוי שגיאות](/doc/guide/basics.entry#debug-mode).

~~~
[php]
Yii::log($message, $level, $category);
Yii::trace($message, $category);
~~~

בעת תיעוד הודעה, אנו צריכים להגדיר את הקטגוריה והרמה שלו. קטגוריה הינה סטרינג בפורמט של `xxx.yyy.zzz` בדומה [שמות מקוצרים](/doc/guide/basics.namespace). לדוגמא, אם ההודעה מתועדת תחת [CController], אנו יכולים להשתמש בקטגוריה `system.web.CController`. רמת ההודעה צריכה להיות אחד מהערכים הבאים:

- `trace`: זוהי הרמה הנמצאת בשימוש על ידי [Yii::trace]. היא נועדה לעקוב אחר תהליך יצירת האפליקציה בזמן הפיתוח.

- `info`: רמה זו נועדה לתיעוד של הודעות כלליות.

- `profile`: רמה זו נועדה לתיעוד של הודעות פרופיל, אשר נרחיב עליהם בהמשך.

- `warning`: רמה זו נועדה לתיעוד של הודעות אזהרה.

- `error`: רמה זו נועדה לתיעוד של הודעות שגיאה.

ניתוב הודעות
---------------

הודעות המתועדות על ידי [Yii::log] או [Yii::trace] נשמרות בזיכרון. אנו בדרך כלל צריכים להציג אותם בדפדפן, או לשמור אותם במקום אחסון קבוע כמו קבצים, אימיילים. זה נקרא *ניתוב הודעות*, כלומר, שליחת ההודעות ליעד שונה.

באפליקציות Yii, ניתוב הודעות מנוהל על ידי הרכיב [CLogRouter]. הוא מנהל סט של מה שנקרא *ניתוב תיעודים*. כל נתב מייצג יעד עבור ההודעות. ניתן לבצע פילטר על גבי הודעות המועברות בנתב על פי הרמות והקטגוריות שלהן.

בכדי להשתמש בניתוב הודעות, אנו צריכים להתקין ולטעון מראש את רכיב האפליקציה [CLogRouter]. כמו כן אנו צריכים להגדיר את המאפיין [routes|CLogRouter::routes] עם הנתבים בהם אנו רוצים להשתמש. הקוד הבא מציג דוגמא [לקובץ הגדרות](/doc/guide/basics.application#application-configuration) אשר מוגדר להשתמש עם ניתוב הודעות:

~~~
[php]
array(
    ......
    'preload'=»array('log'),
    'components'=»array(
        ......
        'log'=»array(
            'class'=»'CLogRouter',
            'routes'=»array(
                array(
                    'class'=»'CFileLogRoute',
                    'levels'=»'trace, info',
                    'categories'=»'system.*',
                ),
                array(
                    'class'=»'CEmailLogRoute',
                    'levels'=»'error, warning',
                    'emails'=»'admin@example.com',
                ),
            ),
        ),
    ),
)
~~~

בדוגמא למעלה, יש ברשותנו שני נתבים. הנתב הראשון הינו [CFileLogRoute] השומר את ההודעות בקובץ תחת התיקיה הזמנית באפליקציה. רק ההודעות שרמה שלהן היא `trace` או `info` ושהקטגוריה שלהם מתחילה ב `system` נשמרות. הנתב השני הינו [CEmailLogRoute] אשר שולח את ההודעות לכתובות האימיילים המוגדרות. רק ההודעות שהרמה שלהן היא `error` או `warning` נשלחות.

ניתן להשתמש בסוגי הנתבים הבאים באפליקציות Yii:



   - [CDbLogRoute]: שומר את ההודעות בטבלה במסד הנתונים.
   - [CEmailLogRoute]: שולח את ההודעות אל אימיילים שהוגדרו מראש.
   - [CFileLogRoute]: שומר את ההודעות בקובץ תחת התיקיה הזמנית של האפליקציה.
   - [CWebLogRoute]: מציג את ההודעות בסוף כל עמוד בדפדפן.
   - [CProfileLogRoute]: מציג את הודעות הפרופיל בסוף כל עמוד בדפדפן.

» Info|מידע: ניתוב הודעות מתבצע בסוף הבקשה הנוכחית כשהאירוע [onEndRequest|CApplication::onEndRequest] מתרחש. בכדי לעצור את טעינת הסקריפט וביצוע הבקשה במקום כלשהו, יש לקרוא למתודה [()CApplication::end] במקום `()die` או `()exit`, בגלל ש-[()CApplication::end]  יטען את האירוע [onEndRequest|CApplication::onEndRequest] כדי שיהיה ניתן לתעד ולנתב את ההודעות כראוי.

### סינון הודעות

כפי שכבר ציינו, ניתן לסנן הודעות על פי הרמות והקטגוריות בהם הן נמצאות לפני שהן נשלחות לניתוב כלשהו. זה נעשה על ידי הגדרת המאפיינים [levels|CLogRoute::levels] ו [categories|CLogRoute::categories] של הנתב המדובר. מספר רב של רמות או קטגוריות צריכות להיות משורשרות (מחוברות אחת לשנייה) בעזרת פסיק ( , ).

מאחר וקטגוריות הודעות הם בפורמט של `xxx.yyy.zzz`, אנו יכולים להתייחס אליהם כהיררכית קטגוריות. במיוחד, אנו אומרים ש `xxx` הוא האב של `xxx.yyy` שהוא האב של `xxx.yyy.zzz`. לכן אנו יכולים להשתמש ב-`*.xxx` בכדי לייצג את הקטגוריה `xxx` וכל תתי הקטגוריות הנמצאות תחתיו.

### תיעוד מידע בהקשר מסויים

החל מגרסא 1.0.6, אנו יכולים להגדיר לתעד מידע נוסף בהקשר מסויים, כמו לדוגמא משתנים מוגדרים מראש של PHP (כמו `GET_$` ו `SERVER_$`), מספר מזהה ב Session, שם משתמש וכדומה. זה נעשה על ידי הגדרת המאפיין [CLogRoute::filter] בנתב מסויים לפילטר המתאים.

המערכת מגיעה עם מחלקה נוחה בשם [CLogFilter] שניתן להשתמש בה כפילטר הדרוש ברוב המקרים. כברירת מחדל, [CLogFilter] יתעד הודעות עם משתנים כמו `GET_$` ו `SERVER_$` אשר מכילים בדרך כלל מידע חשוב בהקשר למערכת. כמו כן, ניתן להגדיר את [CLogFilter] כדי שיספק קידומת עבור הודעות עם מספר מזהה יחודי כלשהו, שם משתמש וכדומה, אשר יכול לפשט בצורה משמעותית את החיפוש הגלובלי כשאנו בודקים את ההודעות המתועדות הרבות.

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

~~~
[php]
array(
    ......
    'preload'=»array('log'),
    'components'=»array(
        ......
        'log'=»array(
            'class'=»'CLogRouter',
            'routes'=»array(
                array(
                    'class'=»'CFileLogRoute',
                    'levels'=»'error',
                    'filter'=»'CLogFilter',
                ),
                ...נתבי הודעות נוספים...
            ),
        ),
    ),
)
~~~

החל מגרסא 1.0.7, Yii מאפשרת לשמור את המיקום (קובץ ושורה) שההודעה תועדה עבור הודעות אשר מתועדות על ידי `Yii::trace`. אפשרות זו כבויה כברירת מחלד מאחר והיא משפיעה לרעה על ביצועי המערכת. בכדי להפעיל אפשרות זו, יש להגדיר פשוט משתנה גלובלי `YII_TRACE_LEVEL` בתחילת הסקריפט (בקובץ `index.php` לפני הטעינה של הקובץ `yii.php`) עם ערך הגדול מ-0. Yii תוסיף עבור כל הודעה מתועדת את הקובץ והשורה שבה ההודעה תועדה. המספר המוגדר בערך הגלובלי `YII_TRACE_LEVEL` הוא כדי שהמערכת תדע להציג את עומק הקריאה, זאת אומרת שאם ההודעה תועדה בקובץ שנטען שלישי מתחילת הסקריפט (מהרצת קובץ `index.php`) ואנו הגדרנו את המשתנה `YII_TRACE_LEVEL` למספר 2 רק שני הקבצים האחרונים בדרך להודעה יתועדו. מידע זה שימושי בעיקר בזמן פיתוח מאחר וזה יכול לעזור בזיהוי המקומות בהם ההודעה תועדה.

שימוש במשתנה הגלובלי `YII_TRACE_LEVEL` נעשה בצורה הבאה:

~~~
[php]
define('YII_TRACE_LEVEL', 2);
~~~

תיעוד ביצועים (פרופיל)
---------------------

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

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

~~~
[php]
Yii::beginProfile('blockID');
...חתיכת הקוד שאנו רוצים לבצע עליו את תיעוד הביצועים....
Yii::endProfile('blockID');
~~~

`blockID` הינו שם יחודי המזהה את הקוד הספציפי הזה.

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

בכדי להציג את תוצאות תיעוד הביצועים, אנו צריכים להתקין רכיב אפליקציה בשם [CLogRouter] אשר משתמש בניתוב מסוג [CProfileLogRoute]. זה דומה למה שאנו עושים עם ניתובי הודעות רגילים. הנתב [CProfileLogRoute] יציג את תוצאות הביצועים בסוף העמוד בדפדפן.

### תיעוד ביצועי שאילתות SQL

תיעוד ביצועים הוא שימושי במיוחד בעת השימוש במסד נתונים מאחר ושאילתות SQL הם הגורם העיקרי לצווארי בקבוק באפליקציה. אנו יכולים לציין באופן ידני ביטויים של `beginProfile` ו `endProfile` במקומות מסויימים בכדי למדוד את הזמן הנדרש עבור כל שאילתת SQL, החל מגרסא 1.0.6, Yii מספקת גישה יותר שיטתית כדי לפתור בעיה זו.

על ידי הגדרת המאפיין [CDbConnection::enableProfiling] לערך השווה ל `true` בהגדרות האפליקציה, כל שאילתית SQL שתתבצע תתועד. ניתן להציג תוצאות אלו על ידי שימוש בנתב [CProfileLogRoute] שהצגנו קודם לכן, המציג לנו כמה זמן נמדד עבור כל שאילתת SQL. כמו כן אנו יכולים לקרוא למתודה [()CDbConnection::getStats] כדי לשלוף את מספר שאילתות SQL שבוצעו ואת הזמן הכולל שלקח לבצע אותם.

«div class="revision"»$Id: topics.logging.txt 1147 2009-06-18 19:14:12Z qiang.xue $«/div»