יצירת הערכת מודרניזציה של אפליקציות

הכלי להערכת מודרניזציה של אפליקציות ב-Migration Center (codmod) הוא כלי מבוסס-AI שמבצע אוטומטית את תהליך הערכת המודרניזציה של האפליקציה. בדף הזה מפורטות ההוראות להתקנה, לשימוש ולפתרון בעיות בכלי codmod.

מידע על מבדק מודרניזציה של אפליקציות

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

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

הכלי הזה מיועד לתפקידים הבאים:

  • אדריכלי IT
  • מקבלי החלטות
  • בעלי האפליקציה

המטרה של כלי codmod היא להאיץ את השינוי של האפליקציה על ידי מתן תובנות ברורות לגבי השינויים הנדרשים והיתרונות שמתקבלים מהשינוי של האפליקציה ל- Google Cloud. ‫codmod הוא כלי CLI נייד שמשתמש ב-Gemini כדי לנתח קוד מקור ומספק המלצות שמבוססות על שיטות מומלצות של Google Cloud .

לפני שמתחילים

כדי להשתמש בכלי codmod, צריך לוודא שמתקיימים התנאים הבאים:

  • תחנת עבודה עם Linux או Windows (גרסה 10 ואילך).
  • גישה לפרויקט שמופעל בו Vertex AI API. Google Cloud
  • התקנה של ה-CLI של gcloud בתחנת העבודה. מידע נוסף זמין במאמר בנושא התקנת ה-CLI של gcloud.

תמחור

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

Codebase שורות קוד (LOC) עלות משוערת
adaptive 2.0-flash ‫2.5-pro (ברירת מחדל) 2.5-flash
Spring Petclinic כ-6,500 ‎20$ 2$‎ ‎30$ $4
James Project כ-1,000,000 60$ ‎30$ ‫500$ 40$
Elasticsearch כ-5,000,000 ‫200$ ‫200$ ‫3,000 $ ‫200$

יכול להיות שהערכים האלה גבוהים מדי כי הם לא לוקחים בחשבון את החיסכון האפשרי בגלל:

  • תמחור מוזל לשאילתות קצרות.
  • מחירים מוזלים לשימוש במטמון מרומז.
  • הנחות תמורת התחייבות לשימוש (CUD).

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

מידע נוסף

הכלי משתמש ביכולות המתקדמות של Vertex AI API להבנה ולניתוח קוד. מידע נוסף על המודלים הזמינים והתכונות שלהם מופיע במאמר בנושא מודלים של Google במסמכי התיעוד של Vertex AI API.

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

הגדרה של codmod

בקטע הזה מוסבר איך להתקין את הכלי codmod ואיך לבצע אימות כדי להשתמש בו.

התקנת codmod

Windows

מריצים את הפקודה הבאה ב-Windows PowerShell כדי להוריד את הגרסה האחרונה של codmod:

$version=curl.exe -s https://codmod-release.storage.googleapis.com/latest
curl.exe -O "https://codmod-release.storage.googleapis.com/${version}/windows/amd64/codmod.exe"

Linux

מריצים את הפקודה הבאה כדי להוריד את הגרסה העדכנית של codmod:

version=$(curl -s https://codmod-release.storage.googleapis.com/latest)
curl -O "https://codmod-release.storage.googleapis.com/${version}/linux/amd64/codmod"
chmod +x codmod

כדי להשתמש בפקודה codmod, צריך להוסיף את קובץ ההפעלה לנתיב או ליצור כינוי.

אימות ל Google Cloud

כדי להשתמש בכלי codmod, צריך פרויקט Google Cloud .

  1. מוודאים ש-Vertex AI API מופעל בפרויקט במסוף או באמצעות CLI:

    gcloud services enable aiplatform.googleapis.com --project <project-id>

  2. מוודאים שיש לכם תפקיד roles/aiplatform.user או תפקיד דומה בפרויקט.

  3. כדי לבצע אימות, מריצים את הפקודה הבאה:

    gcloud auth application-default login

לחלופין, אפשר להשתמש בחשבון שירות ולהגדיר את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS. מידע נוסף זמין במאמר הסבר על Application Default Credentials.

ניהול ההגדרה codmod

בקטעים הבאים מוסבר איך להגדיר את codmod באמצעות הפקודה codmod config.

הצגת כל ההגדרות

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

codmod config list

הגדרת ערך ברירת מחדל לדגל

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

codmod config set project "PROJECT_ID"

מחליפים את PROJECT_ID במזהה הפרויקט. Google Cloud

כדי להגדיר את אזור ברירת המחדל, מריצים:

codmod config set region "REGION"

מחליפים את REGION באזור Google Cloud . רשימת האזורים הזמינים אם אתם לא בטוחים באיזה אזור להשתמש, השתמשו באזור us-central1.

קבלת ערך ספציפי

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

codmod config get project

ביטול ההגדרה של ערך ברירת מחדל

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

codmod config unset project

יצירת דוח הערכה של codmod

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

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

כדי ליצור דוח הערכה, מריצים את הכלי codmod עם הדגלים הבאים:

codmod create -c "CODEBASE" -o "OUTPUT"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CODEBASE: מציין את הספרייה שמכילה את קוד המקור לניתוח, ואפשר לציין אותו כמה פעמים.
  • ‫OUTPUT: מציין את הנתיב שבו הדוח שנוצר נשמר. הדוח הוא בפורמט HTML.

אפשר לשנות את פרויקט ברירת המחדל ואת אזור ברירת המחדל באמצעות הדגלים -p "PROJECT_ID" ו--r "REGION", בהתאמה.

אפשר גם לציין את הדגלים האופציונליים הבאים:

  • ‫--modelset [2.0-flash|2.5-flash|2.5-pro|adaptive]: מציין באילו מודלים של Gemini להשתמש. ערך ברירת המחדל הוא 2.5-pro. השימוש ב-Adaptive מאפשר להפחית את העלויות באופן משמעותי, אבל יכול להיות שתהיה פשרה באיכות הדוחות בהשוואה לשימוש ב-2.5-pro.
  • ‫--format <html|markdown|odt|json>: הפורמט שבו נוצר הדוח. ברירת המחדל היא HTML.
  • ‫--allow-large-codebase: כברירת מחדל, codmod יבקש אישור לפני ניתוח בבסיסי קוד גדולים ממיליון שורות קוד – כדי למנוע עלויות גבוהות. האפשרות הזו משמשת כאישור לא אינטראקטיבי. אפשר גם להפעיל את האפשרות הזו כברירת מחדל על ידי הפעלת הפקודה codmod config set allow_large_codebase true.
  • ‫--improve-fidelity: כשהוא מוגדר, codmod יוצר חלקים באופן סדרתי במקום במקביל. הפעולה הזו משפרת את העקביות בין חלקים שונים בדוח הסופי, אבל נדרש זמן ריצה ארוך יותר.
  • ‫--force-include <strings>, --force-exclude <strings>: כברירת מחדל,‏ codmod סורק סיומות קבצים פופולריות, כולל Java, ‏ ‎.NET ו-Python. משתמשים בדגלים האלה כדי לכלול או להחריג סיומות קבצים. הארגומנט חייב להיות ביטוי רגולרי עם תחביר RE2.
  • ‫--experiments: מציינים --experiments=enable_pdf,enable_images כדי לתמוך בקובצי PDF ובתמונות ב-codmod.
  • ‫--context <string>: הקשר נוסף שרוצים לספק לגבי הפרויקט. הכלי לוקח את ההקשר הזה בחשבון כשהוא יוצר את הדוח.
  • ‫--context-file <path>: כמו --context, רק שההקשר מסופק בקובץ הנתון.
  • ‫--supporting-documents <path>: מציין ספרייה של מסמכי תמיכה בנוגע לבסיס הקוד. אפשר להפנות לקבצים בספרייה הזו מההקשר שסופק באמצעות הדגלים --context או --context-file כדי לכלול אותם בניתוח. הפורמטים הנתמכים כוללים טקסט, PDF ותמונות (PNG,‏ JPG,‏ JPEG).

יצירת דוח מלא

אם אתם צריכים ניתוח מלא, אתם יכולים ליצור דוח באמצעות הפקודה create full:

codmod create full -c "~/mycodebase/" -o "report.html"

יצירת דוח שמתמקד בשכבת הנתונים

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

codmod create data-layer -c "CODEBASE" -o "OUTPUT"

יצירת דוח לגבי כוונת טרנספורמציה ספציפית

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

  • ‫Microsoft workload transformation (MICROSOFT_MODERNIZATION): לשימוש עם אפליקציות שפועלות במערכת ההפעלה של מיקרוסופט. ההערכה תתמקד בתהליכי טרנספורמציה שיעדכנו מסגרות שמבוססות על ‎.NET לגרסה העדכנית ביותר, ויצמצמו את התלות ברישיונות של מיקרוסופט.
  • טרנספורמציה של עומסי עבודה בענן (CLOUD_TO_CLOUD): לשימוש עם אפליקציות שפועלות בתשתית של ספקי ענן אחרים. ההערכה תתמקד בשינויים המומלצים להמרת האפליקציה, כמו מיפוי שירותים של ספקי ענן אחרים לשירותים שלGoogle Cloud .
  • המרת Java מדור קודם (JAVA_LEGACY_TO_MODERN): לשימוש באפליקציות שמריצות Java בגרסה Java 8 או בגרסה דומה. הבדיקה תתמקד במציאת תלות בשדרוג ובאזורים בקוד שהושפעו מהמעבר ל-Java 21 (ה-LTS הנוכחי).
  • המרת Java WILDFLY מדור קודם (WILDFLY_LEGACY_TO_MODERN): לשימוש עם בסיסי קוד של Java EE/Jakarta EE שפועלים בגרסאות של שרת אפליקציות WildFly שקודמות לגרסה העדכנית. ההערכה תתמקד בזיהוי תלות בשדרוג ובאזורים בקוד שמושפעים משדרוג גרסת שרת האפליקציות של WildFly, כולל שינויים שנדרשים בגלל הבדלים בתאימות וב-API.
  • העברת אפליקציות C/C++‎ לארכיטקטורת Arm (ARM_MIGRATION): אפשר להשתמש בכלי הזה עם אפליקציות C/C++‎ כדי להעריך את מידת המוכנות שלהן ואת המאמץ שנדרש להעברה מארכיטקטורות מבוססות x86 לארכיטקטורות מבוססות Arm, כמו מכונות וירטואליות של Google Cloud Axion C4A. ההערכה מתמקדת בזיהוי בעיות פוטנציאליות בניידות של קוד, תלות ספציפית בארכיטקטורה, שינויים במערכת ה-build ושיקולי בדיקה שנדרשים למעבר מוצלח ל-Arm מ-Google Cloud או מספק CSP אחר כמו מכונות Graviton של AWS.

כדי ליצור דוח שמתמקד בכוונה, משתמשים בדגל --intent:

codmod create -c "CODEBASE" -o "OUTPUT" --intent "INTENT"

יצירת דוח עם קטעים נוספים

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

  • ‫files: תצוגה היררכית מובנית של תיקיות הפרויקט ותיאור של התוכן בכל תיקייה, כדי לעזור לכם להתמצא בקבצי הפרויקט.
  • ‫classes: קטלוג של מחלקות קוד עם מידע על כל מחלקה והתלות שלה במחלקות אחרות. השפות הנתמכות הן Java ו-C#.

כדי ליצור את הקטעים הנוספים, משתמשים בדגל --optional-sections:

codmod create -c "CODEBASE" -o "OUTPUT" --optional-sections "SECTIONS"

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

יצירת דוח בהתאמה אישית

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

codmod create custom -c "CODEBASE" -o "OUTPUT" --context "CONTEXT"

כברירת מחדל, נעשה שימוש ב-LLM כדי להרחיב את ההקשר שסופק ולהתאים אותו כדי להבטיח שייווצר קטע עקבי. אפשר להשבית את ההתנהגות הזו באמצעות ציון של --improve-context=false.

סימונים נוספים:

  • ‫--from-template <path>: מציין קובץ תבנית שמגדיר את מבנה המסמך בפורמט טקסט או בפורמט PDF. ‫codmod מזהה את המבנה ומבקש אישור להמשך יצירת הדוח.
  • ‫--skip-template-approval: מדלג על בקשת האישור כשמשתמשים בדגל --from-template.

שינוי של דוח קיים

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

פקודות שמשנות דוח ידרשו את הדגלים הבאים:

  • אחת מהאפשרויות --context ו---context-file: מציינים את בקשת השינוי.
  • ‫--from-report: מציין את הנתיב לקובץ הדוח הקיים.
  • ‫--from-section: שם הקטע שישמש כבסיס לקטע חדש (לדוגמה, Overview או Architecture).

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

codmod list-sections --from-report "REPORT"

שינוי קטע בדוח

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

codmod revise section -c "CODEBASE" --from-report "REPORT" \
  -o "REVISED_REPORT" --from-section "SECTION_NAME" \
  --context "CONTEXT"

יצירת חלק חדש בדוח

יוצרים קטע חדש באמצעות הפקודה הבאה:

codmod create section -c "CODEBASE" --from-report "REPORT" \
  -o "REGENERATED_REPORT" --from-section "SECTION_NAME" \
  --context "CONTEXT"
  • הדגל from-section בפקודה create section הוא אופציונלי.
  • כברירת מחדל, נעשה שימוש ב-LLM כדי להרחיב את ההקשר שסופק ולהתאים אותו כדי להבטיח שייווצר קטע עקבי. אפשר להשבית את ההתנהגות הזו על ידי ציון --improve-context=false.

שימו לב לנקודות הבאות:

  • ‫create section ו-revise section תומכים רק בפורמט הדוח html.
  • התגים create section, revise section ו-list-sections מצפים שהדגל --from-report יצביע על דוח בפורמט HTML.

הערכת עלויות ההערכה

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

codmod create --estimate-cost -c "CODEBASE"

אין תמיכה באומדני עלויות לפקודות create section ו-create custom.

הגדרת רמת הפירוט

רמת הפירוט של הפלט מוגדרת באמצעות הדגל --verbosity LEVEL.codmod רמת הפירוט של היומנים היא אחת מהאפשרויות הבאות: debug,‏ info,‏ warn,‏ error או none. ערך ברירת המחדל הוא warn.

בדיקה ועדכון של גרסת codmod CLI

‫codmod CLI יכול לבדוק באופן אוטומטי אם יש גרסה חדשה יותר.

בדיקות אוטומטיות

כל 24 שעות, ה-CLI שולח שאילתה לקטגוריה של Cloud Storage כדי לבדוק אם פורסמה גרסה חדשה יותר של codmod. אם תימצא גרסה חדשה יותר, תוצג הודעת התראה במסוף. ההודעה כוללת את מספר הגרסה החדשה וקישור להורדת העדכון. התהליך הזה עוזר לכם להתעדכן בתכונות החדשות ביותר, בשיפורים ובתיקוני באגים.

השבתת בדיקות הגרסה

אם אתם מעדיפים להשבית את בדיקת הגרסה האוטומטית, אתם יכולים להשתמש בפקודה config set:

codmod config set disable_version_check true

כדי להפעיל מחדש את בדיקת הגרסה, צריך להגדיר את הערך בחזרה ל-false:

codmod config set disable_version_check false

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

codmod config list

השלמה אוטומטית בשורת הפקודה

כלי ה-CLI‏ codmod תומך בהשלמת שורת פקודה של מעטפת עבור Bash‏, Zsh‏, Fish ו-PowerShell. התכונה הזו עוזרת לכם להקליד במהירות פקודות, דגלים וארגומנטים. כדי לראות את האפשרויות הזמינות ולבחור מתוכן, לוחצים על המקש Tab.

היתרונות של ההשלמה האוטומטית:

  • השלמה אוטומטית של פקודות ודגלים: מתחילים להקליד codmod פקודה או דגל ולוחצים על Tab כדי לראות את ההשלמות האפשריות.
  • אפשרויות נוספות: אפשר לראות ערכים תקינים לדגלים מסוימים. לדוגמה:
    • ‫codmod create --modelset [TAB] מציע קבוצות זמינות של מודלים (לדוגמה, 2.0-flash, ‏ 2.5-pro).
    • ‫codmod create --format [TAB] מציע פורמטים של פלט (לדוגמה, html, ‏json, ‏markdown).
    • codmod create --intent [TAB] מציע כוונות מוגדרות מראש.
  • הצעות מבוססות-הקשר: ההשלמה מותאמת לפקודה. לדוגמה:
    • codmod config set [TAB] מציע את מפתחות ההגדרה הזמינים שאפשר להגדיר.
    • codmod config get [TAB] מציע את מפתחות ההגדרה הזמינים שאפשר לקבל.
    • השלמת נתיב לקובץ מוצעת רק לדגלים או לארגומנטים שמצפים לנתיב של קובץ או ספרייה (לדוגמה, --codebase, ‏--output-path). דגלים אחרים, כמו --project, כבר לא מציעים שמות של קבצים.

הפעלת השלמה של פקודות Shell

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

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

# For Bash
codmod completion bash --help

# For Zsh
codmod completion zsh --help

# For Fish
codmod completion fish --help

# For PowerShell
codmod completion powershell --help

לדוגמה, כדי לטעון השלמה של Bash ב-Linux, אפשר להוסיף את השורה הבאה ל-~/.bashrc:

source <(codmod completion bash)

כדי שהשינויים ייכנסו לתוקף, צריך להפעיל מחדש את המעטפת או להפעיל את הפרופיל (לדוגמה, source ~/.bashrc).

פתרון בעיות

  • הגישה נדחתה: אם נתקלתם בשגיאה 'הגישה נדחתה', ודאו שהענקתם הרשאת הפעלה לקובץ הבינארי codmodעל ידי הפעלת הפקודה chmod +x codmod.
  • ה-CLI נראה תקוע: הניתוח יכול להימשך זמן רב, אבל בדרך כלל אפשר לראות את ההתקדמות בסרגל ההתקדמות ב-CLI. אם סרגל ההתקדמות נשאר על 0% אחרי 15 דקות, צריך לוודא שיש לכם מספיק מכסת שימוש במודל הרלוונטי. כברירת מחדל, codmod משתמש במודל gemini-2.5-pro. עם זאת, יכול להיות שזה ישתנה כי קבוצות שונות של מודלים משתמשות במודלים שונים למטרות שונות.

  • דיווח על שגיאות: אם נתקלתם בשגיאה שדורשת בדיקה, כדאי לאסוף את פרטי ניפוי הבאגים כדי לעזור לצוות הפיתוח שלנו. יומנים מספקים פרטים חשובים לפתרון בעיות. מריצים את הפקודה הבאה כדי לאסוף את היומנים, ואז מכווצים ומשתפים את הארכיון שנוצר עם הצוות בכתובת codmod-feedback-external@google.com.

    codmod collect-logs -o "codmod_logs.zip"

רישיונות קוד פתוח

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

version=$(curl -s https://codmod-release.storage.googleapis.com/latest)
curl -O "https://codmod-release.storage.googleapis.com/${version}/THIRD_PARTY_NOTICES.txt"

קבלת תמיכה ושליחת משוב

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

codmod config set disable_usage_reporting true

אפשר לקבל תמיכה ולשלוח משוב בדרכים הבאות:

  • כדי לקבל תמיכה בנושא codmod, לוחצים על הלחצן תמיכה בדוח ה-HTML שנוצר, או שולחים אימייל לכתובת codmod-feedback-external@google.com.
  • כדי לשתף משוב על codmod, לוחצים על הלחצן משוב בדוח ה-HTML שנוצר.