שיטות מעשיות למעקב אחרי יישומי AI גנרטיבי ב-Javascript

1. סקירה כללית

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

בשיעור ה-Lab הזה תלמדו ליצור אפליקציה פשוטה של בינה מלאכותית גנרטיבית. פורסים אותו ב-Cloud Run. וגם להוסיף לו יכולות חיוניות של מעקב ורישום ביומן באמצעות שירותים ומוצרים של ניראות (observability) ב-Google Cloud.

מה תלמדו

  • כתיבת אפליקציה שמשתמשת ב-Vertex AI באמצעות Cloud Shell Editor
  • אחסון קוד האפליקציה ב-GitHub
  • פריסה של קוד המקור של האפליקציה ב-Cloud Run באמצעות CLI של gcloud
  • הוספת יכולות מעקב ורישום ביומן לאפליקציה של AI גנרטיבי
  • שימוש במדדים מבוססי-יומנים
  • הטמעת רישום ביומן ומעקב באמצעות Open Telemetry SDK
  • תובנות לגבי טיפול אחראי בנתונים של AI

2. דרישות מוקדמות

אם אין לכם חשבון Google, תצטרכו ליצור חשבון חדש.

3. הגדרת הפרויקט

  1. נכנסים למסוף Google Cloud באמצעות חשבון Google.
  2. יוצרים פרויקט חדש או בוחרים לעשות שימוש חוזר בפרויקט קיים. כותבים את מזהה הפרויקט שיצרתם או שבחרתם.
  3. מפעילים את החיוב בפרויקט.
    • עלות השלמת שיעור ה-Lab הזה אמורה להיות פחות מ-5$.
    • כדי למנוע חיובים נוספים, תוכלו לפעול לפי השלבים שמפורטים בסוף שיעור ה-Lab הזה כדי למחוק את המשאבים.
    • משתמשים חדשים זכאים לתקופת ניסיון בחינם בשווי 300$‎.
  4. מוודאים שהחיוב מופעל בקטע My projects (הפרויקטים שלי) בחיוב ב-Cloud
    • אם בעמודה Billing account מופיע הערך Billing is disabled בפרויקט החדש:
      1. לוחצים על שלוש הנקודות בעמודה Actions.
      2. לוחצים על שינוי פרטי החיוב.
      3. בוחרים את החשבון לחיוב שבו רוצים להשתמש.
    • אם אתם משתתפים באירוע בשידור חי, סביר להניח שהשם של החשבון יהיה Google Cloud Platform Trial Billing Account.

4. הכנת Cloud Shell Editor

  1. עוברים אל Cloud Shell Editor. אם תוצג ההודעה הבאה עם בקשה לאשר ל-Cloud Shell לבצע קריאה ל-gcloud באמצעות פרטי הכניסה שלכם, לוחצים על Authorize (אישור) כדי להמשיך.
    לוחצים כדי לאשר את Cloud Shell
  2. פותחים את חלון הטרמינל
    1. לוחצים על תפריט שלושת הקווים סמל התפריט של שלושת הקווים.
    2. לוחצים על Terminal (מסוף).
    3. לוחצים על מסוף חדש
      פתיחת טרמינל חדש ב-Cloud Shell Editor.
  3. בתחנה, מגדירים את מזהה הפרויקט:
    gcloud config set project [PROJECT_ID]
    מחליפים את [PROJECT_ID] במזהה הפרויקט. לדוגמה, אם מזהה הפרויקט הוא lab-example-project, הפקודה תהיה:
    gcloud config set project lab-project-id-example
    אם מופיעה ההודעה הבאה, שבה מצוין ש-gcloud מבקש את פרטי הכניסה שלכם ל-GCPI API, לוחצים על Authorize (הרשאה) כדי להמשיך.
    לוחצים כדי לאשר את Cloud Shell
    אם הפעולה הושלמה, אמורה להופיע ההודעה הבאה:
    Updated property [core/project].
    אם מופיע WARNING ונשאלת השאלה Do you want to continue (Y/N)?, סביר להניח שהזנתם את מזהה הפרויקט בצורה שגויה. אחרי שמוצאים את מזהה הפרויקט הנכון, לוחצים על N, על Enter ומנסים להריץ שוב את הפקודה gcloud config set project.
  4. (אופציונלי) אם אתם לא מצליחים למצוא את מזהה הפרויקט, תוכלו להריץ את הפקודה הבאה כדי לראות את מזהי הפרויקטים שלכם, ממוינים לפי זמן היצירה בסדר יורד:
    gcloud projects list \
     --format='value(projectId,createTime)' \
     --sort-by=~createTime

5. הפעלת Google APIs

במסוף, מפעילים את ממשקי Google API הנדרשים לשיעור המעבדה הזה:

gcloud services enable \
     run.googleapis.com \
     cloudbuild.googleapis.com \
     aiplatform.googleapis.com \
     logging.googleapis.com \
     monitoring.googleapis.com \
     cloudtrace.googleapis.com

השלמת הפקודה הזו עשויה להימשך זמן מה. בסוף תופיע הודעה על הצלחה שדומה לזו:

Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.

אם מופיעה הודעת שגיאה שמתחילה ב-ERROR: (gcloud.services.enable) HttpError accessing ומכילה פרטי שגיאה כמו בהמשך, צריך לנסות שוב את הפקודה לאחר עיכוב של דקה או שתיים.

"error": {
  "code": 429,
  "message": "Quota exceeded for quota metric 'Mutate requests' and limit 'Mutate requests per minute' of service 'serviceusage.googleapis.com' ...",
  "status": "RESOURCE_EXHAUSTED",
  ...
}

6. יצירת אפליקציית NodeJS של AI גנרטיבי

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

  1. בטרמינל, יוצרים את הספרייה codelab-o11y:
    mkdir ~/codelab-o11y
  2. משנים את הספרייה הנוכחית ל-codelab-o11y:
    cd ~/codelab-o11y
  3. מאתחלים את package.json של אפליקציית NodeJS:
    npm init -y
  4. מתקינים את החבילה fastify:
    npm install fastify
  5. התקנת חבילות Cloud SDK לצורך אימות ולעבודה עם Vertex AI:
    npm install google-auth-library @google-cloud/vertexai
  6. יוצרים קובץ index.js ופותחים אותו ב-Cloud Shell Editor:
    cloudshell edit index.js
    עכשיו אמור להופיע קובץ ריק בחלון העריכה שמעל מסוף ה-CLI. המסך אמור להיראות כך:
    הצגת Cloud Shell Editor אחרי שמתחילים לערוך את main.go
  7. מעתיקים את הקוד הבא ומדביקים אותו בקובץ index.js הפתוח:
    const { VertexAI } = require('@google-cloud/vertexai');
const { GoogleAuth } = require('google-auth-library');

let generativeModel;
const auth = new GoogleAuth();
auth.getProjectId().then(result => {
  const vertex = new VertexAI({ project: result });
  generativeModel = vertex.getGenerativeModel({
      model: 'gemini-1.5-flash'
  });
});

const fastify = require('fastify')();
const PORT = parseInt(process.env.PORT || '8080');

fastify.get('/', async function (request, reply) {
  const animal = request.query.animal || 'dog';
  const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
  const resp = await generativeModel.generateContent(prompt);
  const html = resp.response.candidates[0].content.parts[0].text;
  reply.type('text/html').send(html);
})

fastify.listen({ host: '0.0.0.0', port: PORT }, function (err, address) {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`codelab-genai: listening on ${address}`);
})
    כעבור כמה שניות, הקוד יישמר באופן אוטומטי ב-Cloud Shell Editor.

פריסת הקוד של אפליקציית ה-AI הכללי ב-Cloud Run

  1. בחלון המסוף, מריצים את הפקודה לפריסה של קוד המקור של האפליקציה ב-Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    אם מופיעה ההודעה הבאה, סימן שהפקודה תיצור מאגר חדש. לוחצים על Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    תהליך הפריסה עשוי להימשך כמה דקות. בסיום תהליך הפריסה יוצג פלט כמו:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. מעתיקים את כתובת ה-URL של שירות Cloud Run שמוצגת לכרטיסייה או לחלון נפרד בדפדפן. לחלופין, אפשר להריץ את הפקודה הבאה בטרמינל כדי להדפיס את כתובת ה-URL של השירות, וללחוץ על כתובת ה-URL שמוצגת תוך כדי לחיצה על המקש Ctrl כדי לפתוח אותה:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    כשפותחים את כתובת ה-URL, יכול להיות שתופיע הודעת השגיאה 500 או ההודעה הבאה:
    Sorry, this is just a placeholder...
    המשמעות היא שהשירותים לא סיימו את הפריסה. ממתינים כמה דקות ומרעננים את הדף. בסוף יופיע טקסט שמתחיל בעובדות משעשעות על כלבים ומכיל 10 עובדות משעשעות על כלבים.

כדאי לנסות ליצור אינטראקציה עם האפליקציה כדי לקבל עובדות מעניינות על בעלי חיים שונים. כדי לעשות זאת, מוסיפים את הפרמטר animal לכתובת ה-URL, כמו ?animal=[ANIMAL], כאשר [ANIMAL] הוא שם של חיה. לדוגמה, אפשר להוסיף את הערך ?animal=cat כדי לקבל 10 עובדות מעניינות על חתולים, או את הערך ?animal=sea turtle כדי לקבל 10 עובדות מעניינות על צבי ים.

7. בדיקת הקריאות ל-Vertex API

ביקורת של קריאות ל-Google API מספקת תשובות לשאלות כמו "מי קורא ל-API מסוים, איפה ומתי?". ביקורת חשובה כשפותרים בעיות באפליקציה, בודקים את צריכת המשאבים או מבצעים ניתוח פורנזי של תוכנה.

יומני ביקורת מאפשרים לעקוב אחרי פעילויות ניהוליות ופעילויות מערכת, וגם לתעד קריאות לפעולות API מסוג 'קריאת נתונים' ו'כתיבת נתונים'. כדי לבדוק בקשות של Vertex AI ליצירת תוכן, צריך להפעיל את יומני הביקורת Data Read במסוף Cloud.

  1. לוחצים על הלחצן הבא כדי לפתוח את הדף Audit Logs במסוף Cloud

  2. מוודאים שבפרויקט שנוצר בשיעור ה-Lab הזה נבחר. הפרויקט שנבחר מוצג בפינה הימנית העליונה של הדף, ממש מתחת לתפריט ההמבורגר:
    התפריט הנפתח של פרויקטים במסוף Google Cloud
    אם צריך, בוחרים את הפרויקט הנכון מתיבת הסימון המשולבת.
  3. בטבלה Data Access audit logs configuration, בעמודה Service, מחפשים את השירות Vertex AI API ובוחרים אותו על ידי סימון התיבה שמשמאל לשם השירות.
    בוחרים ב-Vertex AI API.
  4. בחלונית המידע שמשמאל, בוחרים בסוג הביקורת 'קריאת נתונים'.
    בדיקת יומני קריאת הנתונים
  5. לוחצים על שמירה.

כדי ליצור יומני ביקורת, פותחים את כתובת ה-URL של השירות. כדי לקבל תוצאות שונות, אפשר לרענן את הדף תוך שינוי הערך של הפרמטר ?animal=.

עיון ביומני ביקורת

  1. לוחצים על הלחצן הבא כדי לפתוח את הדף Logs Explorer במסוף Cloud:

  2. מדביקים את המסנן הבא בחלונית Query.
    LOG_ID("cloudaudit.googleapis.com%2Fdata_access") AND
protoPayload.serviceName="aiplatform.googleapis.com"
    חלונית השאילתה היא עורך שנמצא בחלק העליון של הדף Logs Explorer:
    שליחת שאילתות ליומני ביקורת
  3. לוחצים על Run query.
  4. בוחרים אחת מהרשומות ביומן הביקורת ומרחיבים את השדות כדי לבדוק את המידע שנשמר ביומן.
    אפשר לראות פרטים על קריאה ל-Vertex API, כולל השיטה והמודל שבהם נעשה שימוש. אפשר גם לראות את הזהות של מבצע הקריאה ואת ההרשאות שהעניקו הרשאה לקריאה.

8. רישום אינטראקציות עם AI גנרטיבי ביומן

פרמטרים של בקשות API או נתוני תגובה לא מופיעים ביומני הביקורת. עם זאת, המידע הזה יכול להיות חשוב לפתרון בעיות באפליקציה ולניתוח תהליכי העבודה. בשלב הזה אנחנו משלימים את הפער הזה על ידי הוספת רישום ביומן של האפליקציה. הרישום ביומן מתבצע באמצעות שיטת הרישום הרגילה של NodeJS‏ console.log, כדי לכתוב יומנים מובְנים לפלט הרגיל. בשיטה הזו נעשה שימוש ביכולת של Cloud Run לתעד מידע שמודפס לפלט הסטנדרטי ולהטמיע אותו ב-Cloud Logging באופן אוטומטי. כדי לתעד בצורה נכונה את היומנים המובְנים, צריך להגדיר את הפורמט של היומן המודפס בהתאם. פועלים לפי ההוראות הבאות כדי להוסיף ל-NodeJS יכולות של רישום ביומן מובנה.

  1. חוזרים לחלון (או לכרטיסייה) של Cloud Shell בדפדפן.
  2. בטרמינל, פותחים מחדש את index.js:
    cloudshell edit ~/codelab-o11y/index.js
  3. כדי לתעד ביומן את התשובה של המודל:
    1. מאתרים את הקריאה ל-await generativeModel.generateContent() (בשורה 20).
    2. מעתיקים ומדביקים את הקוד שבהמשך בתחילת השורה הבאה.
        console.log(JSON.stringify({
      severity: 'DEBUG',
      message: 'Content is generated',
      animal: animal,
      prompt: prompt,
      response: resp.response,
  }));

פונקציית הטיפול משתנה כדי לקרוא ל-console.log() כדי להדפיס מבנה JSON שהסכימה שלו עומדת בהנחיות לפורמט מובנה. ביומן מתועדים הפרמטר של בעל החיים בבקשה, ההנחיה והתגובה של המודל.

אחרי כמה שניות, השינויים נשמרים באופן אוטומטי ב-Cloud Shell Editor.

פריסת הקוד של אפליקציית ה-AI הכללי ב-Cloud Run

  1. בחלון המסוף, מריצים את הפקודה לפריסה של קוד המקור של האפליקציה ב-Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    אם מופיעה ההודעה הבאה, סימן שהפקודה תיצור מאגר חדש. לוחצים על Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    תהליך הפריסה עשוי להימשך כמה דקות. בסיום תהליך הפריסה יוצג פלט כמו:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. מעתיקים את כתובת ה-URL של שירות Cloud Run שמוצגת לכרטיסייה או לחלון נפרד בדפדפן. לחלופין, אפשר להריץ את הפקודה הבאה בטרמינל כדי להדפיס את כתובת ה-URL של השירות, וללחוץ על כתובת ה-URL שמוצגת תוך כדי לחיצה על המקש Ctrl כדי לפתוח אותה:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    כשפותחים את כתובת ה-URL, יכול להיות שתופיע הודעת השגיאה 500 או ההודעה הבאה:
    Sorry, this is just a placeholder...
    המשמעות היא שהשירותים לא סיימו את הפריסה. ממתינים כמה דקות ומרעננים את הדף. בסוף יופיע טקסט שמתחיל בעובדות משעשעות על כלבים ומכיל 10 עובדות משעשעות על כלבים.

כדי ליצור יומני אפליקציות, פותחים את כתובת ה-URL של השירות. כדי לקבל תוצאות שונות, אפשר לרענן את הדף תוך שינוי הערך של הפרמטר ?animal=.
כדי לראות את יומני האפליקציה:

  1. לוחצים על הלחצן הבא כדי לפתוח את הדף Logs Explorer במסוף Cloud:

  2. מדביקים את המסנן הבא בחלונית Query‏ (#2 בממשק של Logs Explorer):
    LOG_ID("run.googleapis.com%2Fstdout") AND
severity=DEBUG
  3. לוחצים על Run query.

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

9. ספירת אינטראקציות עם AI גנרטיבי

Cloud Run כותב מדדים מנוהלים שאפשר להשתמש בהם כדי לעקוב אחרי שירותים שנפרסו. מדדי מעקב בניהול המשתמשים מספקים יותר שליטה בנתונים ובתדירות של עדכון המדדים. כדי להטמיע מדד כזה, צריך לכתוב קוד שאוסף נתונים וכותב אותם ב-Cloud Monitoring. בשלב הבא (אופציונלי) מוסבר איך מטמיעים את הפתרון באמצעות OpenTelemetry SDK.

בשלב הזה מוצגת אלטרנטיבה להטמעת מדד משתמשים בקוד – מדדים שמבוססים על יומנים. מדדים שמבוססים על יומנים מאפשרים ליצור מדדי מעקב מהרשומות ביומן שהאפליקציה כותבת ב-Cloud Logging. נשתמש ביומני האפליקציה שהטמענו בשלב הקודם כדי להגדיר מדד שמבוסס על יומנים של מספר הסוגים. המדד יספר את מספר הקריאות המוצלחות ל-Vertex API.

  1. מעיינים בחלון של Logs Explorer שבו השתמשנו בשלב הקודם. מתחת לחלונית השאילתה, מאתרים את התפריט הנפתח Actions ולוחצים עליו כדי לפתוח אותו. התפריט מופיע בצילום המסך שלמטה:
    סרגל הכלים של תוצאות השאילתה עם התפריט הנפתח 'פעולות'
  2. בתפריט שנפתח, בוחרים באפשרות Create metric כדי לפתוח את החלונית Create log-based metric.
  3. כדי להגדיר מדד חדש של מונה בחלונית Create log-based metric (יצירת מדד שמבוסס על יומן):
    1. מגדירים את סוג המדד: בוחרים באפשרות מספר.
    2. מגדירים את השדות הבאים בקטע פרטים:
      • Log metric name: מגדירים את השם כ-model_interaction_count. חלות הגבלות מסוימות על שמות. פרטים נוספים זמינים במאמר פתרון בעיות בנושא הגבלות על שמות.
      • תיאור: מזינים תיאור למדד. לדוגמה, Number of log entries capturing successful call to model inference..
      • Units: משאירים את השדה הזה ריק או מזינים את הספרה 1.
    3. משאירים את הערכים בקטע בחירת מסנן. שימו לב שבשדה Build filter מופיע אותו מסנן ששימש אותנו כדי לראות את יומני האפליקציות.
    4. (אופציונלי) מוסיפים תווית שתעזור לספור את מספר השיחות לכל חיה. הערה: התווית הזו עלולה להגדיל באופן משמעותי את עוצמת הקבוצה (cardinality) של המדד, ולא מומלץ להשתמש בה בסביבת הייצור:
      1. לוחצים על הוספת תווית.
      2. מגדירים את השדות הבאים בקטע Labels:
        • Label name: מגדירים את השם כ-animal.
        • תיאור: מזינים את התיאור של התווית. לדוגמה, Animal parameter.
        • Label type (סוג התווית): בוחרים באפשרות STRING.
        • שם השדה: מקלידים jsonPayload.animal.
        • ביטוי רגולרי: משאירים את השדה ריק.
      3. לוחצים על סיום
    5. לוחצים על Create metric (יצירת מדד) כדי ליצור את המדד.

אפשר גם ליצור מדד שמבוסס על יומנים מהדף מדדים שמבוססים על יומנים, באמצעות הפקודה gcloud logging metrics create ב-CLI או באמצעות משאב Terraform של google_logging_metric.

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

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

  1. לוחצים על הלחצן שלמטה כדי לפתוח את הדף Metrics Explorer במסוף Cloud:

  2. בסרגל הכלים של חלונית הכלי ליצירת שאילתות, בוחרים בלחצן < > MQL או בלחצן < > PromQL. המיקום של הלחצן מוצג בתמונה שבהמשך.
    המיקום של הלחצן &#39;לוח מודעות ליצירת לידים&#39; בכלי הניתוחים של מדדים
  3. מוודאים שהאפשרות PromQL מסומנת במתג Language. המתג לשינוי השפה נמצא באותה סרגל הכלים שמאפשר לעצב את השאילתה.
  4. מזינים את השאילתה בעורך Queries:
    sum(rate(logging_googleapis_com:user_model_interaction_count{monitored_resource="cloud_run_revision"}[${__interval}]))
    מידע נוסף על השימוש ב-PromQL זמין במאמר PromQL ב-Cloud Monitoring.
  5. לוחצים על Run Query. יוצג תרשים קו שדומה לצילום המסך הזה:
    הצגת המדדים שהוגשה לגביהם שאילתה

    הערה: כשהלחצן הפעלה אוטומטית מופעל, הכפתור הרצת השאילתה לא מוצג.

10. (אופציונלי) שימוש ב-Open Telemetry למעקב ולניתוח נתונים

כפי שצוין בשלב הקודם, אפשר להטמיע מדדים באמצעות OpenTelemetry (Otel) SDK. מומלץ להשתמש ב-Otel בארכיטקטורות של מיקרו-שירותים. בשלב הזה מתוארים הנושאים הבאים:

  • איך מפעילים את רכיבי OTel כדי לתמוך במעקב ובניטור של האפליקציה
  • איך מאכלסים את תצורת OTel במטא-נתונים של המשאבים בסביבת Cloud Run
  • הוספת כלים לאפליקציית flask עם יכולות מעקב אוטומטיות
  • הטמעת מדד מונה כדי לעקוב אחרי מספר הקריאות המוצלחות למודלים
  • קורלציה בין המעקב ליומני האפליקציה

הארכיטקטורה המומלצת לשירותים ברמת המוצר היא להשתמש ב-OTel collector כדי לאסוף ולעבד את כל נתוני הניראות לשירות אחד או יותר. הקוד בשלב הזה לא משתמש באוסף, מטעמי פשטות. במקום זאת, הוא משתמש בייצוא של OTel שכותב נתונים ישירות ל-Google Cloud.

הגדרת רכיבי OTel למעקב אחר נתונים ומדדים

  1. חוזרים לחלון (או לכרטיסייה) של Cloud Shell בדפדפן.
  2. מתקינים את החבילות הנדרשות לשימוש בכלי למדידה אוטומטית של OpenTelemetry:
    npm install @opentelemetry/sdk-node \
  @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/instrumentation-express \
  @opentelemetry/instrumentation-http \
  @opentelemetry/sdk-metrics \
  @opentelemetry/sdk-trace-node \
  @google-cloud/opentelemetry-cloud-trace-exporter \
  @google-cloud/opentelemetry-cloud-monitoring-exporter \
  @google-cloud/opentelemetry-resource-util
  3. בטרמינל, יוצרים קובץ חדש בשם setup.js:
    cloudshell edit ~/codelab-o11y/setup.js
  4. מעתיקים ומדביקים את הקוד שבהמשך בעורך כדי להגדיר את המעקב והניטור של OpenTelemetry.
    const opentelemetry = require("@opentelemetry/api");
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { MeterProvider, PeriodicExportingMetricReader } = require("@opentelemetry/sdk-metrics");
const { AlwaysOnSampler, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { Resource } = require('@opentelemetry/resources');
const { ATTR_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');
const { FastifyInstrumentation } = require('@opentelemetry/instrumentation-fastify');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { TraceExporter } = require("@google-cloud/opentelemetry-cloud-trace-exporter");
const { MetricExporter } = require("@google-cloud/opentelemetry-cloud-monitoring-exporter");
const { GcpDetectorSync } = require("@google-cloud/opentelemetry-resource-util");

module.exports = { setupTelemetry };

function setupTelemetry() {
  const gcpResource = new Resource({
    [ATTR_SERVICE_NAME]: process.env.K_SERVICE,
  }).merge(new GcpDetectorSync().detect())

  const tracerProvider = new NodeTracerProvider({
    resource: gcpResource,
    sampler: new AlwaysOnSampler(),
    spanProcessors: [new SimpleSpanProcessor(new TraceExporter({
      // will export all resource attributes that start with "service."
      resourceFilter: /^service\./
    }))],
  });
  registerInstrumentations({
    tracerProvider: tracerProvider,
    instrumentations: [
      // Express instrumentation expects HTTP layer to be instrumented
      new HttpInstrumentation(),
      new FastifyInstrumentation(),
    ],
  });
  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
  tracerProvider.register();

  const meterProvider = new MeterProvider({
    resource: gcpResource,
    readers: [new PeriodicExportingMetricReader({
      // Export metrics every second (default quota is 30,000 time series ingestion requests per minute)
      exportIntervalMillis: 1_000,
      exporter: new MetricExporter(),
    })],
  });
  opentelemetry.metrics.setGlobalMeterProvider(meterProvider);
}
  5. חוזרים לטרמינל ופותחים מחדש את index.js:
    cloudshell edit ~/codelab-o11y/index.js
  6. מחליפים את הקוד בגרסה שמפעילה את המעקב והאיסוף של מדדים ב-OpenTelemetry, ומעדכנת את מונה הביצועים בכל הפעלה מוצלחת. כדי לעדכן את הקוד, מוחקים את תוכן הקובץ ומעתיקים ומדביקים את הקוד שבהמשך:
    const { VertexAI } = require('@google-cloud/vertexai');
const { GoogleAuth } = require('google-auth-library');

let generativeModel, traceIdPrefix;
const auth = new GoogleAuth();
auth.getProjectId().then(result => {
  const vertex = new VertexAI({ project: result });
  generativeModel = vertex.getGenerativeModel({
        model: 'gemini-1.5-flash'
  });
  traceIdPrefix = `projects/${result}/traces/`;
});

// setup tracing and monitoring OTel providers
const { setupTelemetry }= require('./setup');
setupTelemetry();

const { trace, context } = require('@opentelemetry/api');
function getCurrentSpan() {
  const current_span = trace.getSpan(context.active());
  return {
      trace_id: current_span.spanContext().traceId,
      span_id: current_span.spanContext().spanId,
      flags: current_span.spanContext().traceFlags
  };
};

const opentelemetry = require("@opentelemetry/api");
const meter = opentelemetry.metrics.getMeter("genai-o11y/nodejs/workshop/example");
const counter = meter.createCounter("model_call_counter");

const fastify = require('fastify')();
const PORT = parseInt(process.env.PORT || '8080');

fastify.get('/', async function (request, reply) {
  const animal = request.query.animal || 'dog';
  const prompt = `Give me 10 fun facts about ${animal}. Return this as html without backticks.`
  const resp = await generativeModel.generateContent(prompt)
  const span = getCurrentSpan();
  console.log(JSON.stringify({
      severity: 'DEBUG',
      message: 'Content is generated',
      animal: animal,
      prompt: prompt,
      response: resp.response,
      "logging.googleapis.com/trace": traceIdPrefix + span.trace_id,
      "logging.googleapis.com/spanId": span.span_id,
  }));
  counter.add(1, { animal: animal });
  const html = resp.response.candidates[0].content.parts[0].text;
  reply.type('text/html').send(html);
});

fastify.listen({ host: '0.0.0.0', port: PORT }, function (err, address) {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`codelab-genai: listening on ${address}`);
});

האפליקציה משתמשת עכשיו ב-OpenTelemetry SDK כדי לבדוק את ביצוע הקוד באמצעות מעקב (tracing) ולהטמיע ספירה של מספר ההפעלות המוצלחות כמדד. השיטה main() משתנה כדי להגדיר את היצואנים של OpenTelemetry למעקב אחר נתונים ומדדים, כך שיכתבו ישירות ל-Google Cloud Tracing and Monitoring. הוא מבצע גם הגדרות נוספות כדי לאכלס את הנתונים והמדדים שנאספו במטא-נתונים שקשורים לסביבת Cloud Run. הפונקציה Handler() מתעדכנת כדי להגדיל את מונה המדד בכל פעם שהקריאה ל-Vertex AI API מחזירה תוצאות תקינות.

אחרי כמה שניות, השינויים נשמרים באופן אוטומטי ב-Cloud Shell Editor.

פריסת הקוד של אפליקציית ה-AI הכללי ב-Cloud Run

  1. בחלון המסוף, מריצים את הפקודה לפריסה של קוד המקור של האפליקציה ב-Cloud Run.
    gcloud run deploy codelab-o11y-service \
     --source="${HOME}/codelab-o11y/" \
     --region=us-central1 \
     --allow-unauthenticated
    אם מופיעה ההודעה הבאה, סימן שהפקודה תיצור מאגר חדש. לוחצים על Enter.
    Deploying from source requires an Artifact Registry Docker repository to store built containers.
A repository named [cloud-run-source-deploy] in region [us-central1] will be created.

Do you want to continue (Y/n)?
    תהליך הפריסה עשוי להימשך כמה דקות. בסיום תהליך הפריסה יוצג פלט כמו:
    Service [codelab-o11y-service] revision [codelab-o11y-service-00001-t2q] has been deployed and is serving 100 percent of traffic.
Service URL: https://codelab-o11y-service-12345678901.us-central1.run.app
  2. מעתיקים את כתובת ה-URL של שירות Cloud Run שמוצגת לכרטיסייה או לחלון נפרד בדפדפן. לחלופין, אפשר להריץ את הפקודה הבאה בטרמינל כדי להדפיס את כתובת ה-URL של השירות, וללחוץ על כתובת ה-URL שמוצגת תוך כדי לחיצה על המקש Ctrl כדי לפתוח אותה:
    gcloud run services list \
     --format='value(URL)' \
     --filter='SERVICE:"codelab-o11y-service"'
    כשפותחים את כתובת ה-URL, יכול להיות שתופיע הודעת השגיאה 500 או ההודעה הבאה:
    Sorry, this is just a placeholder...
    המשמעות היא שהשירותים לא סיימו את הפריסה. ממתינים כמה דקות ומרעננים את הדף. בסוף יופיע טקסט שמתחיל בעובדות משעשעות על כלבים ומכיל 10 עובדות משעשעות על כלבים.

כדי ליצור נתוני טלמטריה, פותחים את כתובת ה-URL של השירות. כדי לקבל תוצאות שונות, אפשר לרענן את הדף תוך שינוי הערך של הפרמטר ?animal=.

ניתוח נתוני מעקב של אפליקציות

  1. לוחצים על הלחצן הבא כדי לפתוח את הדף Trace Explorer במסוף Cloud:

  2. בוחרים אחת מהטראקים האחרונים. אמורים להופיע 5 או 6 span שדומים לצילום המסך שבהמשך.
    תצוגה של טווח האפליקציה ב-Trace Explorer
  3. מאתרים את ה-span שמתעד את הקריאה למטפל באירוע (השיטה fun_facts). זה יהיה ה-span האחרון עם השם /.
  4. בחלונית Trace details בוחרים באפשרות Logs & events. יוצגו יומני אפליקציות שתואמים ל-span הספציפי הזה. הזיהוי של הקורלציה מתבצע באמצעות מזהי המעקב והקטע בנתוני המעקב וביומן. אמורה להופיע יומן האפליקציה שבו נכתבה ההנחיה והתגובה של Vertex API.

הסבר על מדד המונה

  1. לוחצים על הלחצן שלמטה כדי לפתוח את הדף Metrics Explorer במסוף Cloud:

  2. בסרגל הכלים של חלונית הכלי ליצירת שאילתות, בוחרים בלחצן < > MQL או בלחצן < > PromQL. המיקום של הלחצן מוצג בתמונה שבהמשך.
    המיקום של הלחצן &#39;לוח מודעות ליצירת לידים&#39; בכלי הניתוחים של מדדים
  3. מוודאים שהאפשרות PromQL מסומנת במתג Language. המתג לשינוי השפה נמצא באותה סרגל הכלים שמאפשר לעצב את השאילתה.
  4. מזינים את השאילתה בעורך Queries:
    sum(rate(workload_googleapis_com:model_call_counter{monitored_resource="generic_task"}[${__interval}]))
  5. לוחצים על הרצת השאילתה.כשהמתג הרצה אוטומטית מופעל, הלחצן הרצת השאילתה לא מוצג.

11. (אופציונלי) ערפול מידע רגיש ביומני

בשלב 10 רשמנו ביומן מידע על האינטראקציה של האפליקציה עם מודל Gemini. המידע הזה כלל את שם החיה, את ההנחיה בפועל ואת התשובה של המודל. אמנם אחסון המידע הזה ביומן אמור להיות בטוח, אבל זה לא בהכרח נכון לגבי תרחישים רבים אחרים. ההנחיה עשויה לכלול מידע אישי או מידע רגיש אחר שהמשתמש לא רוצה שיאוחסן. כדי לטפל בבעיה הזו, אפשר להסתיר את המידע הרגיש שנכתב ב-Cloud Logging. כדי לצמצם את השינויים בקוד, מומלץ להשתמש בפתרון הבא.

  1. יצירת נושא PubSub לאחסון רשומות יומן נכנסות
  2. יוצרים בור נתוני יומנים שמנתב מחדש יומנים שסוננו לנושא PubSub.
  3. יוצרים צינור עיבוד נתונים של Dataflow שמשנה יומנים שמנותבים לנושא PubSub לפי השלבים הבאים:
    1. קריאת רשומה ביומן מהנושא ב-PubSub
    2. בדיקת המטען הייעודי (payload) של הרשומה כדי לאתר מידע אישי רגיש באמצעות DLP inspection API
    3. צנזור המידע הרגיש בתוכן המשא באמצעות אחת משיטות הצנזור של DLP
    4. כתיבת רשומת היומן המעורפלת ב-Cloud Logging
  4. פריסת צינור עיבוד הנתונים

12. (אופציונלי) הסרת המשאבים

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

  1. כדי למחוק את הפרויקט, מריצים את הפקודה delete project בטרמינל:
    PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete ${PROJECT_ID} --quiet
    מחיקת הפרויקט ב-Cloud תפסיק את החיוב על כל המשאבים ו-APIs שבהם נעשה שימוש באותו פרויקט. אמורה להופיע ההודעה הבאה, שבה PROJECT_ID הוא מזהה הפרויקט:
    Deleted [https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID].

You can undo this operation for a limited period by running the command below.
    $ gcloud projects undelete PROJECT_ID

See https://cloud.google.com/resource-manager/docs/creating-managing-projects for information on shutting down projects.
  2. (אופציונלי) אם מופיעה שגיאה, צריך לפעול לפי שלב 5 כדי למצוא את מזהה הפרויקט שבו השתמשתם במהלך הסדנה. מחליפים אותו בפקודה שמופיעה בהוראה הראשונה. לדוגמה, אם מזהה הפרויקט הוא lab-example-project, הפקודה תהיה:
    gcloud projects delete lab-project-id-example --quiet

13. מזל טוב

בשיעור ה-Lab הזה יצרתם אפליקציית בינה מלאכותית גנרטיבית שמשתמשת במודל Gemini כדי ליצור תחזיות. וגם הוסיפו לאפליקציה יכולות חיוניות של מעקב ורישום ביומן. פרסתם את האפליקציה ואת השינויים מקוד המקור ב-Cloud Run. לאחר מכן, תוכלו להשתמש במוצרי Google Cloud Observability כדי לעקוב אחרי ביצועי האפליקציה, וכך להבטיח את המהימנות שלה.

אם אתם רוצים להשתתף במחקר בנושא חוויית משתמש (UX) כדי לשפר את המוצרים שבהם עבדתם היום, אפשר להירשם כאן.

ריכזנו כאן כמה אפשרויות להמשך הלמידה: