הקדמה
פתרון להרשמה אפקטיבית חיוני להצלחת כל יישום. Winston הוא ספריית הרשמה רבת השימושיות והפופולרית עבור יישומי Node.js. בין תכונותיו של Winston ניתן למצוא תמיכה באפשרויות אחסון מרובות, רמות הרשמה, שאילתות הרשמה, ופרופילר מובנה.
במדריך זה, תשתמש ב-Winston כדי לרשום את היישום של Node/Express שתיצור כחלק מתהליך זה. תראה גם איך לשלב את Winston עם Morgan, עוד מעטף רישום בקשות HTTP פופולרי עבור Node.js, כדי לאחד יומני נתוני בקשות HTTP עם מידע נוסף. לאחר השלמת המדריך הזה, שרת ה-Ubuntu שלך ירוץ את היישום הקטן של Node/Express, ו-Winston יישמש לרשום שגיאות והודעות לקובץ ולמסוף.
דרישות מוקדמות
כדי לעקוב אחרי המדריך הזה, תצטרך:
-
שרת Ubuntu 20.04 עם משתמש לא-רוט שמורשה לפעולות sudo, שניתן להגדיר על ידי המעקב אחרי הגדרת השרת הראשונית.
-
Node.js מותקן באמצעות ה-PPA הרשמי (ארכיון של חבילות אישי), כפי שמוסבר ב-איך להתקין את Node.js על Ubuntu 20.04, אפשרות 2.
שלב 1 — יצירת אפליקציה בסיסית ב-Node/Express
Winston נהוג לשימוש כדי ליישם רישומים של אירועים מיישומי אינטרנט שנבנו בעזרת Node.js. בשלב זה, תיצור אפליקצית אינטרנט פשוטה ב-Node.js באמצעות ספריית הפריים Express. תשתמש ב-express-generator
, כלי שורת פקודה, כדי להפעיל מהר אפליקציה אינטרנט ב-Node/Express.
מכיוון שהתקנת את מנהל החבילות של Node במקום הנדרש, ניתן להשתמש בפקודת npm
כדי להתקין את express-generator
:
הדגל -g
מתקין את החבילה באופן גלובלי, מה שפירושו שניתן להשתמש בה ככלי שורת פקודה מחוץ לפרויקט/מודול Node קיים.
עם express-generator
מותקן, ניתן ליצור את האפליקציה שלך באמצעות הפקודה express
, בעקבות שם התיקייה שבה ברצונך להשתמש לפרויקט:
במסגרת המדריך הזה, הפרויקט יקרא myApp
.
הערה: ניתן גם להפעיל את כלי ה- express-generator
ישירות בלי להתקין אותו גלובלית כפקודת מערכת בתחילה. כדי לעשות זאת, הפעל את הפקודה הבאה:
הפקודה npx
היא מנהל פקודות שנשלח עם מנהל החבילות של Node, שמקל על הפעלת כלים שורת הפקודה ממאגר החבילות של npm.
במהלך ההפעלה הראשונית, היא תשאל אותך האם אתה מסכים להוריד את החבילה:
Need to install the following packages:
express-generator
Ok to proceed? (y)
ענה y
ולחץ על ENTER
. עכשיו ניתן להשתמש ב- npx express-generator
במקום express
.
בשלב הבא, התקן את Nodemon, שיכול לטעון מחדש את האפליקציה באופן אוטומטי בכל פעם שתבצע שינויים. יישום Node.js צריך להתחיל מחדש בכל פעם שנעשים שינויים בקוד המקור כדי שהשינויים האלה ייכנסו לתוקף, לכן Nodemon ישמור על צפייה אוטומטית בשינויים ויפעיל מחדש את היישום. מאחר שאתה רוצה להשתמש ב- nodemon
ככלי שורת פקודה, התקן אותו עם הדגל -g
:
כדי לסיים את הגדרת היישום, עבור לתיקיית היישום והתקן את התלויות כך:
ברירת המחדל, יישומים שנוצרו עם express-generator
רצים על פורט 3000
, ולכן עליך לוודא שהגדרות הגנה אינן חוסמות את הפורט.
כדי לפתוח את הפורט 3000
, הרץ את הפקודה הבאה:
עכשיו יש לך את כל הדברים שאתה צריך כדי להתחיל את היישום האינטרנט שלך. כדי לעשות זאת, הרץ את הפקודה הבאה:
הפקודה הזו מפעילה את היישום על פורט 3000
. ניתן לבדוק אם הוא פועל על ידי כתובת דפדפן שלך אל http://your_server_ip:3000
. עליך לראות משהו דומה לזה:
בנקודה זו, תוכל להתחיל בסשן SSH שני לשרת שלך לשארית המדריך הזה, ולהשאיר את היישום האינטרנטי שפתחת בסשן המקורי פועל. למען הסר ספק, הסשן SSH הראשוני שבו מופעל היישום יקרא סשן A. כל הפקודות בסשן A יופיעו על רקע כחול-כהה כמו זו:
תשתמש בסשן SSH החדש להרצת פקודות ועריכת קבצים. סשן זה יקרא סשן B. כל הפקודות בסשן B יופיעו על רקע כחול בהיר כמו זו:
למעט אם נציין אחרת, יש להריץ את כל הפקודות הנותרות בסשן B.
בשלב זה, יצרת את היישום הבסיסי. למען המרקורים, תתאים אותו.
שלב 2 — התאמת משתני הלוגים
בעוד היישום ברירת המחדל שנוצר על ידי express-generator
הוא התחלה טובה, עליך להתאים את היישום כך שיקרא לאיתור הלוגר הנכון כאשר זה נדרש.
express-generator
כולל את Middleware ללוגינג של HTTP שנקרא Morgan שתשתמש בו כדי להירשם נתונים אודות כל בקשת HTTP. מאחר ו-Morgan תומך בפלט של נתונים, הוא פועל בהתאמה טובה עם תמיכת הזרמים שנבנתה בתוך Winston, מאפשרת לך לאגד יומני נתוני בקשת HTTP עם כל דבר אחר שתבחר להירשם אליו עם Winston.
התבנית של express-generator
משתמשת במשתנה logger
כאשר מתייחסת לחבילת morgan
. מאחר ותשתמש ב-Morgan וב-Winston, שני החבילות ללוגינג, יכול להיות מבלבל לקרוא לאחת מהן logger
. כדי לציין איזה משתנה אתה רוצה, תוכל לשנות את ההצהרות של המשתנים על ידי עריכת קובץ app.js
.
כדי לפתוח את app.js
לעריכה, השתמש ב־nano
או בעורך הטקסט האהוב עליך:
מצא את השורה הבאה ליד הראש של הקובץ:
שנה את שם המשתנה מ־logger
ל־morgan
:
העדכון הזה מציין שהמשתנה שנצהרף morgan
יקרא לשיטת require()
המקושרת ללוגר בקשת Morgan.
אתה צריך למצוא איפה אחרת המשתנה logger
הוזכר בקובץ ולשנות אותו ל-morgan
. תצטרך גם לשנות את פורמט הלוג שמשמש בחבילת morgan
ל-combined
, שהוא הפורמט התקני של לוג אפאצ'י ויכלול מידע שימושי בלוגים, כגון כתובת IP חיצונית וכותרת הבקשה HTTP של משתמש ה-Agent.
כדי לעשות זאת, מצא את השורה הבאה:
עדכן אותה לשורה הבאה:
השינויים הללו יעזרו לך להבין איזה חבילת לוגים הוזכרת בכל זמן נתון לאחר השילוב של תצורת Winston.
כאשר סיימת, שמור וסגור את הקובץ.
עכשיו שהאפליקציה שלך מוכנה, אתה יכול להתחיל לעבוד עם Winston.
שלב 3 — התקנה והגדרת Winston
בשלב זה, תתקין ותגדיר את Winston. תבחן גם את האפשרויות להגדרה הזמינות כחלק מחבילת winston
ותיצור מקליט כדי ליישם מידע לקובץ ולקונסולה.
התקן את winston
בעזרת הפקודה הבאה:
מומלץ לשמור קבצי תמיכה או הגדרה לכלי היישום שלך בתיקייה מיוחדת. צור תיקיית config
שתכיל את התצורה של winston
:
לְבַצֵעַ זאת, צרו תיקייה שתכיל את קבצי הלוג:
לבסוף, התקינו את app-root-path
:
החבילה app-root-path
שימושית כאשר מציינים נתיבים ב-Node.js. אף על פי שהחבילה הזו אינה ישירות קשורה ל-Winston, היא מועילה בהגדרת נתיבים לקבצים ב-Node.js. תשתמש בה כדי לציין את מיקום קבצי הלוג של Winston משורש הפרויקט וכדי למנוע תחביר נתיבים יחסים לא יפים.
עכשיו שהתצורה לטיפול בלוגים מוכנה, ניתן להגדיר את ההגדרות שלך. צרו ופתחו את ~/myApp/config/winston.js
לעריכה:
הקובץ winston.js
יכיל את התצורה שלך ל-Winston.
באשר להוספת הקוד הבא כדי לדרוש את החבילות app-root-path
ו-winston
:
עם המשתנים האלה במקום, אתה יכול להגדיר את ההגדרות ל-העבורות שלך. העבורות הם מושג שהוצג על ידי Winston שמתייחס למנגנון האחסון/הפלט המשמש ללוגים. Winston מגיע עם ארבע עבורות ליבה מובנות: Console, File, HTTP, ו-Stream.
תתמקד בהעבורות לקונסולה ולקובץ עבור המדריך הזה. ההעברה לקונסולה תופעל מידע לקונסולה, וההעברה לקובץ תופעל מידע לקובץ מסוים. כל הגדרת העבורה יכולה להכיל הגדרות הגדרה, כמו גודל קובץ, רמות לוגים, ופורמט לוגים.
הנה סיכום מהיר של ההגדרות שתשתמש בהן עבור כל העבורה:
רמה
: רמת הודעות להתיעוד.שם_קובץ
: הקובץ שישמש לרישום נתוני הלוג.handleExceptions
: תפוס ורשום יוצאי דופן שלא נתפסו.maxsize
: גודל מקסימלי של קובץ הלוג, בבתים, לפני שיווצר קובץ חדש.maxFiles
: הגבלת מספר הקבצים שנוצרים כאשר גודל קובץ הלוג חורג.format
: כיצד הפלט של הלוג יופורמט.
רמות הלוג מציינות עדיפות של הודעות ומסומנות במספר שלם. Winston משתמש ברמות הלוג של npm שמתוחזקות מ-0 עד 6 (הגבוהה ביותר עד הנמוכה ביותר):
- 0: שגיאה
- 1: אזהרה
- 2: מידע
- 3: http
- 4: מפורט
- 5: דיבוג
- 6: מטופש
כאשר מציינים רמת לוג עבור תחביר מסוים, יורשם כל דבר ברמה זו או מעליה. לדוגמה, כאשר מגדירים רמה של מידע
, כל דבר ברמה שגיאה
, אזהרה
, או מידע
יירשם.
רמות הלוג מוגדרות בזמן שימוש בלוגר, שזה אומר שניתן להריץ את הפקודה הבאה כדי לרשום שגיאה: logger.error('הודעת שגיאה בדיקה')
.
עדיין בקובץ התצורה, הוסף את הקוד הבא כדי להגדיר את הגדרות התצורה עבור התחבירים קובץ
ו- קונסולה
בהגדרת winston
:
בשלב הבא, יש להוסיף את הקוד הבא כדי ליצור מופע חדש של מנוע הלוגים winston
עם תחבורות קובץ ומסוף באמצעות המאפיינים המוגדרים במשתנה options
:
באופן ברירת המחדל, morgan
מוציא פלט למסוף בלבד, לכן עליך להגדיר פונקציית זרימה שתוכל לקבל פלט הנוצר על ידי morgan
ולהעביר אותו לקבצי הלוג של winston
. יש להשתמש ברמת הלוג info
כדי לאפשר את הפלט בשני התחבורות (קובץ ומסוף). יש להוסיף את הקוד הבא לקובץ התצורה:
לבסוף, יש להוסיף את הקוד לייצוא המנוע כך שיוכל לשמש בחלקים אחרים של היישום:
קובץ התצורה המושלם של winston
יראה כעת כך:
שמור וסגור את הקובץ.
עכשיו יש לך את הלוגר מוגדר, אך היישום שלך עדיין לא מודע אליו, או כיצד להשתמש בו, כך שעליך לאינטגרציה את הלוגר עם היישום.
שלב 4 — אינטגרציה של Winston עם היישום
כדי להפעיל את הלוגר שלך עם היישום, עליך להודיע ל־express
על כך. ראית בשלב 2 שתצורת ה־express
נמצאת ב־app.js
, כך שתוכל לייבא את הלוגר שלך אל הקובץ הזה.
פתח את הקובץ לעריכה:
הוסף הגדרת משתנה winston
ליד הקידום של הקובץ עם ההצהרות האחרות של require
:
המקום הראשון שתשתמש בו winston
הוא עם morgan
. עדיין ב-app.js
, מצא את השורה הבאה:
עדכן אותה כך שתכלול את האפשרות stream
:
כאן, אתה מגדיר את האפשרות stream
לממשק הניקוד שיצרת כחלק מתצורת winston
.
שמור וסגור את הקובץ.
בשלב זה, הגדרת את היישום שלך ב-Express כך שיעבוד עם Winston. הבא, תסתכל על נתוני היומן.
שלב 5 — גישה לנתוני היומן ורישום הודעות היומן מותאמות אישית
כעת שהיישום הוגדר, אתה מוכן לראות נתוני יומן. בשלב זה, תבדוק את רשומות היומן ותעדכן את ההגדרות שלך עם הודעת יומן מותאמת אישית לדוגמה.
אם תטען מחדש את העמוד בדפדפן האינטרנט, תראה משהו דומה לפלט הבא בקונסול של חיבור SSH A:
Output[nodemon] restarting due to changes...
[nodemon] starting `node bin/www`
info: ::1 - - [25/Apr/2022:18:10:55 +0000] "GET / HTTP/1.1" 200 170 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36"
info: ::1 - - [25/Apr/2022:18:10:55 +0000] "GET /stylesheets/style.css HTTP/1.1" 304 - "http://localhost:3000/" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36"
ישנן שתי רשומות יומן כאן: הראשונה עבור הבקשה אל עמוד ה-HTML; השנייה עבור גליון הסגנון המתאים. מאחר שכל תחבורה מוגדרת לטפל בנתוני יומן ברמת info
, אתה צריך גם לראות מידע דומה בתחבורת הקובץ הממוקמת ב-~/myApp/logs/app.log
.
כדי להציג את תוכן קובץ היומן, הפעל את הפקודה הבאה:
tail
יפליט את החלקים האחרונים של הקובץ בטרמינל שלך.
אתה צריך לראות משהו דומה לזה:
{"level":"info","message":"::1 - - [25/Apr/2022:18:10:55 +0000] \"GET / HTTP/1.1\" 304 - \"-\" \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36\"\n","timestamp":"2022-04-25T18:10:55.573Z"}
{"level":"info","message":"::1 - - [25/Apr/2022:18:10:55 +0000] \"GET /stylesheets/style.css HTTP/1.1\" 304 - \"http://localhost:3000/\" \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36\"\n","timestamp":"2022-04-25T18:10:55.588Z"}
הפלט בקובץ ההעברה ייכתב כאובייקט JSON מאחר שהשתמשת ב־winston.format.json()
ב־format
אופציה להגדרת ההעברה של הקובץ. תוכל ללמוד עוד על JSON ב־מבוא ל־JSON.
עד כה, הלוגר שלך רק מקליט בקשות HTTP ונתונים קשורים. מידע זה חיוני להיות בלוגים שלך.
בעתיד, ייתכן שתרצה לרשום הודעות לוג מותאמות אישית, כמו לרשום שגיאות או לפרופול את ביצועי שאילתות מסד הנתונים. כדוגמה, תקרא ללוגר מנתב מטפל בשגיאות. כברירת מחדל, חבילת express-generator
כוללת כבר מנתבי טיפול בשגיאות 404
ו־500
, כך שתעבוד עם זה.
פתח את הקובץ ~/myApp/app.js
:
מצא את הבלוק הקוד בתחתית הקובץ שנראה כמו זה:
סעיף זה הוא מנתב טיפול בשגיאות הסופי שישלח בסופו של דבר תגובת שגיאה חזרה ללקוח. מאחר שכל השגיאות בצד השרת יעברו דרך נתיב זה, זו מקום טוב לכלול את הלוגר של winston
.
כי כעת אתה מתמודד עם שגיאות, ברצונך להשתמש ברמת הלוג error
. שני הטרנספורטים מוגדרים להקליט הודעות ברמת error
, אז תראה את הפלט בלוג המסך ובקובץ.
אתה יכול לכלול כל דבר שתרצה בלוג, כולל מידע כמו:
err.status
: קוד מצב שגיאת HTTP. אם לא קיים, ברירת מחדל היא500
.err.message
: פרטי השגיאה.req.originalUrl
: כתובת ה-URL שנשלחה בבקשה.req.path
: החלק של נתיב ב-URL של הבקשה.req.method
: שיטת ה-HTTP של הבקשה (GET, POST, PUT, וכו').req.ip
: כתובת IP רחוקה של הבקשה.
עדכן את נתיב מנהל השגיאות כך שיכלול את הלוג של winston
:
שמור וסגור את הקובץ.
כדי לבדוק את התהליך הזה, נסה לגשת לעמוד שאינו קיים בפרויקט שלך. לגשת לעמוד שאינו קיים תזרוק שגיאת 404. בדפדפן האינטרנט שלך, נסה לטעון את כתובת ה-URL הבאה: http://כתובת_ה-IP_של_השרת_שלך:3000/foo
. בזכות תבנית המקור שנוצרה על ידי express-generator
, היישום מוגדר כך שיתגוב לשגיאה כזו.
הדפדפן שלך יציג הודעת שגיאה דומה לזו:
כאשר אתה מסתכל על הקונסול במהלך חיבור SSH A, יש צורך לראות רשומת לוג עבור השגיאה. בזכות הפורמט colorize
שנמצא, יהיה קל לזהות אותה:
Output[nodemon] starting `node bin/www`
error: 404 - Not Found - /foo - GET - ::1
info: ::1 - - [25/Apr/2022:18:08:33 +0000] "GET /foo HTTP/1.1" 404 982 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36"
info: ::1 - - [25/Apr/2022:18:08:33 +0000] "GET /stylesheets/style.css HTTP/1.1" 304 - "http://localhost:3000/foo" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36"
בנוגע לקובץ הלוגים, בעת הרצת פקודת tail
שוב תראה את הרשומות החדשות בלוג:
תראה הודעה כמו הבאה:
{"level":"error","message":"404 - Not Found - /foo - GET - ::1","timestamp":"2022-04-25T18:08:33.508Z"}
ההודעת שגיאה כוללת את כל הנתונים שהוראת ל־winston
לרשום כחלק ממטפל השגיאות. המידע יכלול את מצב השגיאה (404 – לא נמצא), כתובת ה־URL המבוקשת (localhost/foo
), אופן הבקשה (GET
), כתובת ה־IP של הבקשה, וחותמת הזמן שבה נעשתה הבקשה.
מסקנה
במדריך זה, בנית יישום אינטרנט פשוט ב־Node.js ואינטגרצת פתרון הלוגים של Winston שישמש ככלי יעיל לספק תובנות בביצועי היישום.
תיעוד שידורי Winston. הוספת שידורים מותאמים אישית. winstond
. פרופילים.