מילון מונחים של פרוטוקול Event Build

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

הפעולה בוטלה

בניגוד לאירועים אחרים, ל-Aborted אין סוג מזהה תואם, כי אירוע Aborted מחליף אירועים מסוגים אחרים. האירוע הזה מצביע על כך שה-build הסתיים מוקדם יותר ומזהה האירוע שהוא מופיע בו לא נוצר באופן רגיל. Aborted מכיל תיאור 'אנום' וידידותי לבני אדם שמסביר את הסיבה להשלמת ה-build.

לדוגמה, אם ה-build מעריך יעד כאשר המשתמש מפריע ל-Bazel, BEP מכיל אירוע כמו:

{
  "id": {
    "targetCompleted": {
      "label": "//:foo",
      "configuration": {
        "id": "544e39a7f0abdb3efdd29d675a48bc6a"
      }
    }
  },
  "aborted": {
    "reason": "USER_INTERRUPTED"
  }
}

פעולה שבוצעה

כולל פרטים על הביצוע של פעולה ספציפית ב-build. כברירת מחדל, האירוע הזה נכלל ב-BEP רק עבור פעולות שנכשלו, כדי לזהות את הגורם העיקרי לכשלים ב-build. המשתמשים יכולים להגדיר את הסימון --build_event_publish_all_actions כך שיכלול את כל אירועי ActionExecuted.

גרסת build

אירוע יחיד ב-BuildFinished נשלח אחרי שהפקודה הושלמה, וכולל קוד היציאה של הפקודה. האירוע הזה מספק מידע מהימן על הצלחה/נכשל.

מטא-נתונים של Build

מכיל את התוכן המנותח של הדגל --build_metadata. מטרת האירוע היא לשלב את Bazel בכלים אחרים באמצעות צנרת חיצונית (כמו מזהים).

מדדי Build

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

לתשומת ליבך, ייתכן שהקובץ memory_metrics לא יאוכלס אם לא היה איסוף אשפה ב-Java במהלך ביצוע הפקודה. המשתמשים יכולים להגדיר את האפשרות --memory_profile=/dev/null שמאלצת את כלי איסוף האשפה לפעול בסוף הפקודה כדי לאכלס את memory_metrics.

{
  "id": {
    "buildMetrics": {}
  },
  "buildMetrics": {
    "actionSummary": {
      "actionsExecuted": "1"
    },
    "memoryMetrics": {},
    "targetMetrics": {
      "targetsLoaded": "9",
      "targetsConfigured": "19"
    },
    "packageMetrics": {
      "packagesLoaded": "5"
    },
    "timingMetrics": {
      "cpuTimeInMs": "1590",
      "wallTimeInMs": "359"
    }
  }
}

תאריך התחלה

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

יומני BuildToolLogs

אירוע אחד (BuildToolLogs) נשלח בסוף פקודה, כולל מזהי URI של קבצים שנוצרו על ידי כלי ה-build, שעשויים לעזור בהבנה או בניפוי באגים בהתנהגות כלי ה-build. ייתכן שחלק מהמידע ייכלל בשורה.

{
  "id": {
    "buildToolLogs": {}
  },
  "lastMessage": true,
  "buildToolLogs": {
    "log": [
      {
        "name": "elapsed time",
        "contents": "MC4xMjEwMDA="
      },
      {
        "name": "process stats",
        "contents": "MSBwcm9jZXNzOiAxIGludGVybmFsLg=="
      },
      {
        "name": "command.profile.gz",
        "uri": "file:///tmp/.cache/bazel/_bazel_foo/cde87985ad0bfef34eacae575224b8d1/command.profile.gz"
      }
    ]
  }
}

שורת הפקודה

ארגון BEP מכיל מספר אירועי CommandLine שמכילים ייצוגים של כל הארגומנטים בשורת הפקודה (כולל אפשרויות וארגומנטים שלא פורשו). לכל אירוע CommandLine יש תווית בStructuredCommandLineId שמציינת איזה ייצוג הוא מעביר. שלושה אירועים כאלה מופיעים ב-BEP:

• "original": שורת הפקודה שוחזרה כמו Bazel התקבלה מהלקוח ב-Bazel, ללא אפשרויות הפעלה שמקורן בקובצי .rc
• "canonical": שורת הפקודה האפקטיבית עם קובצי rc .מורחבים שמופעלת בהתאם למדיניות ההפעלה.
• "tool": מאוכלס מהאפשרות --experimental_tool_command_line. זו פעולה שימושית להעביר את שורת הפקודה של כלי העטיפה של Bazel דרך BEP. ההודעה יכולה להיות הודעות טקסט בינאריות בקידוד נתונים בינאריים מסוג CommandLine64 שנעשה בהן שימוש ישיר, או מחרוזת שמנותח אבל לא מתורגם (כי האפשרויות של הכלי עשויות להיות שונות מ-Bazel's).

הגדרה

אירוע Configuration נשלח עבור כל configuration ביעדים ברמה העליונה ב-build. תמיד קיים אירוע הגדרה אחד לפחות. id משתמש ב-TargetConfigured וב-TargetComplete מזהי אירועים כדי לעשות הבחנה בין האירועים ב-build של הגדרות אישיות רבות.

{
  "id": {
    "configuration": {
      "id": "a5d130b0966b4a9ca2d32725aa5baf40e215bcfc4d5cdcdc60f5cc5b4918903b"
    }
  },
  "configuration": {
    "mnemonic": "k8-fastbuild",
    "platformName": "k8",
    "cpu": "k8",
    "makeVariable": {
      "COMPILATION_MODE": "fastbuild",
      "TARGET_CPU": "k8",
      "GENDIR": "bazel-out/k8-fastbuild/bin",
      "BINDIR": "bazel-out/k8-fastbuild/bin"
    }
  }
}

מזהה נוחות

ניסיוני. אם האפשרות --experimental_convenience_symlinks_bep_event מוגדרת, נוצר אירוע יחיד של ConvenienceSymlinksIdentified באמצעות פקודות build שמציינות איך יש לנהל את הקישורים החכמים בסביבת העבודה. הכלים האלה מאפשרים לבנות כלים שמפעילים את Bazel מרחוק, ולארגן את סביבת העבודה המקומית כאילו מדובר ב-Bazel לפרסום מקומי.

{
  "id": {
    "convenienceSymlinksIdentified":{}
  },
  "convenienceSymlinksIdentified": {
    "convenienceSymlinks": [
      {
        "path": "bazel-bin",
        "action": "CREATE",
        "target": "execroot/google3/bazel-out/k8-fastbuild/bin"
      },
      {
        "path": "bazel-genfiles",
        "action": "CREATE",
        "target": "execroot/google3/bazel-out/k8-fastbuild/genfiles"
      },
      {
        "path": "bazel-out",
        "action": "CREATE",
        "target": "execroot/google3/bazel-out"
      }
    ]
  }
}

שליפה

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

NamedSetOfFiles

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

למידע נוסף על פרשנות האירועים של NamedSetOfFiles בסטרימינג, ניתן לעיין בדף הדוגמאות של BEP.

אפשרויות ניתוח

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

{
  "id": {
    "optionsParsed": {}
  },
  "optionsParsed": {
    "startupOptions": [
      "--max_idle_secs=10800",
      "--noshutdown_on_low_sys_mem",
      "--connect_timeout_secs=30",
      "--output_user_root=/tmp/.cache/bazel/_bazel_foo",
      "--output_base=/tmp/.cache/bazel/_bazel_foo/a61fd0fbee3f9d6c1e30d54b68655d35",
      "--deep_execroot",
      "--expand_configs_in_place",
      "--idle_server_tasks",
      "--write_command_log",
      "--nowatchfs",
      "--nofatal_event_bus_exceptions",
      "--nowindows_enable_symlinks",
      "--noclient_debug",
    ],
    "cmdLine": [
      "--enable_platform_specific_config",
      "--build_event_json_file=/tmp/bep.json"
    ],
    "explicitCmdLine": [
      "--build_event_json_file=/tmp/bep.json"
    ],
    "invocationPolicy": {}
  }
}

דפוס מורחב

PatternExpanded אירועים מציינים את הקבוצה של כל היעדים שתואמים לתבניות שסופקו בשורת הפקודה. כדי ליצור פקודות מוצלחות, אירוע יחיד קיים בכל התבניות בPatternExpandedId ובכל היעדים בילדים של האירוע PatternExpanded. אם התבנית מתרחבת לtest_suite קבוצת יעדי הבדיקה הכלולים ב-test_suite. כל תבנית לא תטופל באמצעות BEP, כי היא מכילה אירוע Aborted נוסף עם PatternExpandedId שמזהה את הדפוס.

{
  "id": {
    "pattern": {
      "pattern":["//base:all"]
    }
  },
  "children": [
    {"targetConfigured":{"label":"//base:foo"}},
    {"targetConfigured":{"label":"//base:foobar"}}
  ],
  "expanded": {
    "testSuiteExpansions": {
      "suiteLabel": "//base:suite",
      "testLabels": "//base:foo_test"
    }
  }
}

ההתקדמות

אירועי התקדמות מכילים את הפלט הסטנדרטי ואת השגיאה הרגילה שהופקו על ידי Bazel במהלך ביצוע הפקודה. בנוסף, האירועים האלה נוצרים באופן אוטומטי לפי הצורך כדי להודיע על אירועים שלא הוכרזו על ידי אירוע לוגי "הורה" (במיוחד, NamedSetOfFiles).

יעד מלא

עבור כל שילוב (target, configuration, aspect) שמשלים את שלב הביצוע, אירוע TargetComplete נכלל ב-BEP. האירוע מכיל את הכיתוב 'מטרה/הצלחה' של היעד ואת קבוצות הפלט המבוקשות של היעד.

{
  "id": {
    "targetCompleted": {
      "label": "//examples/py:bep",
      "configuration": {
        "id": "a5d130b0966b4a9ca2d32725aa5baf40e215bcfc4d5cdcdc60f5cc5b4918903b"
      }
    }
  },
  "completed": {
    "success": true,
    "outputGroup": [
      {
        "name": "default",
        "fileSets": [
          {
            "id": "0"
          }
        ]
      }
    ]
  }
}

יעד מוגדר

עבור כל יעד שמשלים את שלב הניתוח, אירוע TargetConfigured נכלל ב-BEP. זהו המקור המוסמך למאפיין יעד&PLURAL39;s"כלל התצורות שחלות על היעד מופיעות בילדות האירוע.

לדוגמה, יצירה באמצעות האפשרויות --experimental_multi_cpu עשויה ליצור את האירוע TargetConfigured הבא עבור יעד יחיד עם שתי הגדרות אישיות:

{
  "id": {
    "targetConfigured": {
      "label": "//starlark_configurations/multi_arch_binary:foo"
    }
  },
  "children": [
    {
      "targetCompleted": {
        "label": "//starlark_configurations/multi_arch_binary:foo",
        "configuration": {
          "id": "c62b30c8ab7b9fc51a05848af9276529842a11a7655c71327ade26d7c894c818"
        }
      }
    },
    {
      "targetCompleted": {
        "label": "//starlark_configurations/multi_arch_binary:foo",
        "configuration": {
          "id": "eae0379b65abce68d54e0924c0ebcbf3d3df26c6e84ef7b2be51e8dc5b513c99"
        }
      }
    }
  ],
  "configured": {
    "targetKind": "foo_binary rule"
  }
}

סיכום יעד

עבור כל צמד של (target, configuration) שמופעל, אירוע TargetSummary כולל תוצאת הצלחה מצטברת שכוללת את הביצוע של היעד המוגדר ואת כל ההיבטים שהוחלו על היעד שהוגדר.

תוצאת הבדיקה

אם תתקבל בקשה לבדיקה, יישלח אירוע TestResult לכל ניסיון בדיקה, חיתוך והרצת בדיקה. כך לקוחות BEP יכולים לזהות במדויק אילו פעולות בדיקה נכשלו בבדיקות שלהם ולזהות את פלטי הבדיקה (כגון יומנים, קובצי test.xml) לכל פעולת בדיקה.

סיכום סיכום הבדיקה

אם מתבקשים לבצע בדיקה, נשלח אירוע TestSummary עבור כל בדיקה (target, configuration), שמכיל מידע הדרוש לפירוש תוצאות הבדיקה. כולל מספר הניסיונות, הפיצולים וההפעלות בכל בדיקה, כדי לאפשר לצרכנים של נתוני BEP להבדיל בין פריטי מידע שונים במאפיינים האלה. החישובים וההפעלות בכל בדיקה נלקחים בחשבון בעת יצירת TestStatus המצטברים כדי להבדיל בין FLAKY בדיקות לבין FAILED בדיקות.

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

בניגוד ל-Commandline, אירוע זה מכיל את דגלי שורת הפקודה שלא נותחו בצורת מחרוזת, שכלי ה-build נתקל בהם אחרי שהרחיב את כל הקבצים של .bazelrc והתייחס לסימון --config.

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

הגדרת Workspace

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

סטטוס Workspace

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