مسرد مصطلحات بروتوكول الأحداث

لكل نوع من أحداث BEP دلالات خاصة به، على أن يتم توثيقها إلى حدٍ أدنى في build_event_stream.proto. يصف مسرد المصطلحات التالي كل نوع حدث.

تم الإلغاء

على عكس الأحداث الأخرى، لا يتوفّر نوع معرّف مقابل Aborted لأنّ الفعالية Aborted تحل محل أنواع أخرى. يشير هذا الحدث إلى أنّ الإصدار قد تم إنهاؤه في وقت مبكر وأنّ معرّف الحدث الذي يظهر ضمنه لم يتم إنتاجه بشكل طبيعي. يتضمن Aborted وصفًا تعداديًا ومناسبًا للبشر لتوضيح سبب عدم اكتمال الإصدار.

على سبيل المثال، إذا كان الإصدار يقيّم هدفًا عندما يقاطع المستخدم Bazel، يتضمن محتوى BEP حدثًا مثل ما يلي:

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

تم تنفيذ الإجراء

تقدّم تفاصيل حول تنفيذ إجراء معيّن في مبنى. يتم تضمين هذا الحدث تلقائيًا في BEP فقط للإجراءات التي تعذّر تنفيذها، وذلك للمساعدة في تحديد السبب الأساسي لتعذُّر الإصدار. يمكن للمستخدمين ضبط العلامة --build_event_publish_all_actions لتضمين جميع أحداث ActionExecuted.

تم الانتهاء من الإصدار

يتم إرسال حدث BuildFinished واحد بعد اكتمال الأمر ويشمل رمز الخروج للأمر. توفّر هذه الفعالية معلومات موثوقة عن نجاح/تعذّر اجتياز الاختبار.

البيانات الوصفية للإصدار

تحتوي على محتوى تم تحليله للعلامة --build_metadata. يهدف هذا الحدث إلى دعم دمج Bazel مع الأدوات الأخرى من خلال تشغيل البيانات الخارجية (مثل المعرّفات).

مقاييس الإصدار

يتم إرسال حدث BuildMetrics واحد في نهاية كل أمر ويتضمّن عدّادات/مقاييس مفيدة لقياس سلوك أداة الإصدار أثناء تنفيذ الأمر. تشير هذه المقاييس إلى العمل الذي تم تنفيذه فعليًا ولا تحتسب العمل المُخزَّن مؤقتًا الذي تمت إعادة استخدامه.

وتجدر الإشارة إلى أنّه قد لا تتم تعبئة 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 بيانات وصفية تصف الأمر قبل بدء أي عمل مفيد.

سجلات LogTool

يتم إرسال حدث BuildToolLogs واحد في نهاية الأمر، بما في ذلك معرّفات الموارد المنتظمة (URI) للملفات التي تم إنشاؤها باستخدام أداة الإصدار والتي قد تساعد في فهم سلوك أداة الأداة أو تصحيحها. وقد يتم تضمين بعض المعلومات في هذه الصفحة.

{
  "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. يمكن أن تكون هذه الرسالة عبارة عن رسالة مؤقتة ببروتوكول CommandLine مشفّرة بنظام Base64 ويتم استخدامها مباشرةً، أو سلسلة يتم تحليلها ولكن لا يتم تفسيرها (لأن خيارات الأداة قد تختلف عن Bazel').

عملية الإعداد

يتم إرسال الحدث Configuration لكل configuration مستخدَم في الأهداف ذات المستوى الأعلى في مبنى. هناك حدث إعداد واحد على الأقل دائمًا. ويُعاد استخدام id من خلال رقمَي تعريف الحدثَين TargetConfigured وTargetComplete، ويُعدّ ذلك ضروريًا للتفريق بين هذه الأحداث من خلال إصدارات متعدّدة الإعدادات.

{
  "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 event's children. إذا تم توسيع النمط إلى أي 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 أثناء تنفيذ الأوامر. ويتم أيضًا إنشاء هذه الأحداث تلقائيًا حسب الحاجة للإعلان عن الأحداث التي لم يتم الإعلان عنها من خلال الحدث المنطقي "parent". (خصوصًا، NamedSetOfFiles.)

مكتملة

بالنسبة إلى كل تركيبة من (target, configuration, aspect) تُكمل مرحلة التنفيذ، يتم تضمين حدث TargetComplete في BEP. يحتوي الحدث على مدى النجاح/التعذُّر على مستوى الهدف&39، ومجموعات الاستهداف المطلوبة.

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

Targetconfig:

بالنسبة إلى كل هدف يُكمل مرحلة التحليل، يتم تضمين حدث TargetConfigured في BEP. وهذا هو المصدر الموثوق للسمة target's "rule;" . تظهر الإعدادات التي تم تطبيقها على الهدف في الأطفال المُعلنين عن الفعالية.

على سبيل المثال، قد يؤدي إنشاء الخيارات --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، يحمل هذا الحدث علامات سطر الأوامر التي لم يتم تحليلها في نموذج السلسلة كما تظهر بواسطة أداة الإصدار بعد توسيع جميع ملفات .bazelrc ومراعاة العلامة --config.

قد يتم الاعتماد على الحدث UnstructuredCommandLine لإعادة إنتاج تنفيذ الأمر المحدّد بدقة.

ضبط Workspace

يحتوي حدث WorkspaceConfig واحد على معلومات الضبط حول مساحة العمل، مثل جذر التنفيذ.

حالة Workspace

يحتوي حدث WorkspaceStatus واحد على نتيجة أمر حالة مساحة العمل.