Microsoft مهام سير عمل إطار عمل العامل - إمكانية المراقبة

توفر إمكانية المراقبة رؤى حول الحالة الداخلية وسلوك مهام سير العمل أثناء التنفيذ. يتضمن ذلك إمكانات التسجيل والمقاييس والتتبع التي تساعد في مراقبة مهام سير العمل وتصحيحها.

Tip

تعد إمكانية المراقبة ميزة على مستوى إطار العمل ولا تقتصر على مهام سير العمل. لمزيد من المعلومات، راجع إمكانية الملاحظة.

بصرف النظر عن القياس عن بعد GenAI القياسي، تصدر مهام سير عمل إطار عمل العامل امتدادات وسجلات ومقاييس إضافية لتوفير رؤى أعمق حول تنفيذ سير العمل. تساعد ميزات المراقبة هذه المطورين على فهم تدفق الرسائل وأداء المنفذين وأي أخطاء قد تحدث.

تمكين إمكانية المراقبة

يرجى الرجوع إلى تمكين إمكانية المراقبة للحصول على إرشادات حول تمكين إمكانية المراقبة في تطبيقاتك.

يرجى الرجوع إلى تمكين إمكانية المراقبة للحصول على إرشادات حول تمكين إمكانية المراقبة في تطبيقاتك.

نطاقات سير العمل

يتم إصدار الامتدادات التالية أثناء تنفيذ سير العمل:

اسم النطاق Description
workflow.build يتم إصداره لكل بناء سير عمل.
workflow.session النطاق الخارجي الذي يمثل مدة بقاء تنفيذ سير العمل بأكملها، من البداية حتى الإيقاف أو الخطأ.
workflow_invoke يتم إصدارها لكل دورة إدخال إلى توقف داخل جلسة عمل سير العمل.
executor.process {executor_id} يتم إرسالها لكل منفذ يقوم بمعالجة رسالة. يتم إلحاق معرف المنفذ باسم النطاق.
edge_group.process يتم إرسالها لكل مجموعة حافة تعالج رسالة.
message.send يتم إرسالها لكل رسالة يتم إرسالها من منفذ إلى منفذ آخر.

يتم إصدار الامتدادات التالية أثناء تنفيذ سير العمل:

اسم النطاق Description
workflow.build يتم إصداره لكل بناء سير عمل.
workflow.run يتم إصدارها لكل تنفيذ لسير العمل.
executor.process {executor_id} يتم إرسالها لكل منفذ يقوم بمعالجة رسالة. يتم إلحاق معرف المنفذ باسم النطاق.
edge_group.process {edge_group_type} يتم إرسالها لكل مجموعة حافة تعالج رسالة. يتم إلحاق نوع مجموعة الحافة باسم النطاق.
message.send يتم إرسالها لكل رسالة يتم إرسالها من منفذ إلى منفذ آخر.

يتم إصدار الامتدادات التالية أثناء تنفيذ سير العمل:

اسم النطاق Description
workflow.build يتم إصداره لكل بناء سير عمل.
workflow.session النطاق الخارجي الذي يمثل مدة بقاء جلسة تنفيذ سير العمل.
workflow_invoke يتم إصدارها لكل دورة إدخال إلى توقف داخل جلسة عمل سير العمل.
executor.process {executor_id} يتم إرسالها لكل منفذ يقوم بمعالجة رسالة. يتم إلحاق معرف المنفذ باسم النطاق.
edge_group.process يتم إرسالها لكل مجموعة حافة تعالج رسالة.
message.send يتم إرسالها لكل رسالة يتم إرسالها من منفذ إلى آخر.

خصائص المدى

تحمل الامتدادات سمات توفر سياقا إضافيا حول العملية. يتم تعيين السمات التالية على نطاقات سير العمل:

Attribute امتداد (امتدادات) Description
workflow.id workflow.build، workflow.session المعرف الفريد لسير العمل.
workflow.name workflow.session اسم سير العمل.
workflow.description workflow.session وصف سير العمل.
workflow.definition workflow.build تعريف JSON للرسم البياني لسير العمل.
session.id workflow.session معرف جلسة العمل الفريد.
executor.id executor.process المعرف الفريد للمنفذ.
executor.type executor.process اسم نوع المنفذ.
executor.input executor.process رسالة الإدخال. تعيين فقط عند تمكين البيانات الحساسة.
executor.output executor.process إخراج المنفذ. تعيين فقط عند تمكين البيانات الحساسة.
message.type executor.process، message.send اسم نوع الرسالة.
message.content message.send محتوى الرسالة. تعيين فقط عند تمكين البيانات الحساسة.
message.source_id message.send معرف المنفذ الذي أرسل الرسالة.
message.target_id message.send معرف المنفذ الهدف، إذا تم تحديده.
edge_group.type edge_group.process نوع مجموعة الحافة.
edge_group.delivered edge_group.process ما إذا كان قد تم تسليم الرسالة (منطقي).
edge_group.delivery_status edge_group.process نتيجة التسليم (راجع حالة تسليم مجموعة Edge).
error.type أي امتداد عند الخطأ اسم نوع الاستثناء.
Attribute امتداد (امتدادات) Description
workflow.id workflow.build، workflow.run المعرف الفريد لسير العمل.
workflow.name workflow.run اسم سير العمل.
workflow.description workflow.run وصف سير العمل.
workflow.definition workflow.build تعريف JSON للرسم البياني لسير العمل.
workflow_builder.name workflow.build اسم منشئ سير العمل.
workflow_builder.description workflow.build وصف منشئ سير العمل.
executor.id executor.process المعرف الفريد للمنفذ.
executor.type executor.process اسم نوع المنفذ.
message.type executor.process، message.send اسم نوع الرسالة.
message.payload_type executor.process نوع بيانات حمولة الرسالة.
message.destination_executor_id message.send معرف المنفذ الهدف، إذا تم تحديده.
message.source_id edge_group.process معرف المنفذ الذي أرسل الرسالة.
message.target_id edge_group.process معرف المنفذ الهدف، إذا تم تحديده.
edge_group.type edge_group.process نوع مجموعة الحافة.
edge_group.id edge_group.process المعرف الفريد لمجموعة الحافة.
edge_group.delivered edge_group.process ما إذا كان قد تم تسليم الرسالة (منطقي).
edge_group.delivery_status edge_group.process نتيجة التسليم (راجع حالة تسليم مجموعة Edge).
Attribute امتداد (امتدادات) Description
workflow.id workflow.build، workflow.session، workflow_invoke يبدأ سير العمل معرف المنفذ.
workflow.name workflow.session، workflow_invoke اسم سير العمل، عند تعيينه.
workflow.description workflow.session، workflow_invoke وصف سير العمل، عند تعيينه.
workflow.definition workflow.build تعريف JSON للرسم البياني لسير العمل.
session.id workflow.session، workflow_invoke معرف جلسة عمل سير العمل.
executor.id executor.process معرف المنفذ.
executor.implementation.id executor.process معرف تنفيذ المنفذ.
executor.input executor.process رسالة الإدخال. تعيين فقط عند تمكين البيانات الحساسة.
executor.output executor.process إخراج المنفذ. تعيين فقط عند تمكين البيانات الحساسة.
message.type executor.process اسم نوع الرسالة التي تمت معالجتها.
message.content message.send محتوى الرسالة. تعيين فقط عند تمكين البيانات الحساسة.
message.source_id edge_group.process، message.send معرف المنفذ الذي أرسل الرسالة.
message.target_id edge_group.process، message.send معرف المنفذ الهدف، عند تحديده.
edge_group.type edge_group.process نوع مجموعة الحافة التي تتم معالجتها.
edge_group.delivered edge_group.process ما إذا كان قد تم تسليم الرسالة أم لا.
edge_group.delivery_status edge_group.process نتيجة التسليم (راجع حالة تسليم مجموعة Edge).
error.type أي امتداد عند الخطأ اسم نوع الاستثناء.
error.message أي امتداد عند الخطأ رسالة الاستثناء.

أحداث النطاق

أحداث الامتداد هي إدخالات سجل منظمة مرفقة بالامتدادات، ما يوفر مخططا زمنيا لللحظات الرئيسية داخل كل امتداد.

اسم الحدث امتداد (امتدادات) Description
build.started workflow.build يتم إصداره عند بدء عملية الإنشاء.
build.validation_completed workflow.build يتم إصداره عند اجتياز التحقق من صحة البنية.
build.completed workflow.build يتم إصداره عند اكتمال البناء بنجاح.
build.error workflow.build يتم إصداره عند فشل البنية.
session.started workflow.session يتم إصداره عند بدء جلسة عمل سير العمل.
session.completed workflow.session يتم إصداره عند اكتمال جلسة عمل سير العمل.
session.error workflow.session يتم إصداره عندما تواجه جلسة سير العمل خطأ.
workflow.started workflow_invoke يتم إصداره عند بدء استدعاء سير العمل.
workflow.completed workflow_invoke يتم إصداره عند اكتمال استدعاء سير العمل.
workflow.error workflow_invoke يتم إصداره عندما يواجه استدعاء سير العمل خطأ.
اسم الحدث امتداد (امتدادات) Description
build.started workflow.build يتم إصداره عند بدء عملية الإنشاء.
build.validation_completed workflow.build يتم إصداره عند اجتياز التحقق من صحة البنية.
build.completed workflow.build يتم إصداره عند اكتمال البناء بنجاح.
build.error workflow.build يتم إصداره عند فشل البنية.
workflow.started workflow.run يتم إصداره عند بدء تشغيل سير العمل.
workflow.completed workflow.run يتم إصداره عند اكتمال تشغيل سير العمل.
workflow.error workflow.run يتم إصداره عندما يواجه تشغيل سير العمل خطأ.
اسم الحدث امتداد (امتدادات) Description
build.started workflow.build يتم إصداره عند بدء عملية الإنشاء.
build.validation_completed workflow.build يتم إصداره عند اجتياز التحقق من صحة البنية.
build.completed workflow.build يتم إصداره عند اكتمال البناء بنجاح.
build.error workflow.build يتم إصداره عند فشل البنية.
session.started workflow.session يتم إصداره عند بدء جلسة عمل سير العمل.
session.completed workflow.session يتم إصداره عند اكتمال جلسة عمل سير العمل.
session.error workflow.session يتم إصداره عندما تواجه جلسة سير العمل خطأ.
workflow.started workflow_invoke يتم إصداره عند بدء استدعاء سير العمل.
workflow.completed workflow_invoke يتم إصداره عند اكتمال استدعاء سير العمل.
workflow.error workflow_invoke يتم إصداره عندما يواجه استدعاء سير العمل خطأ.

عندما يرسل منفذ رسالة إلى منفذ آخر، يتم إنشاء النطاق message.send كامتداد فرعي للامتداد executor.process . ومع ذلك، فإن executor.process امتداد المنفذ الهدف ليس تابعا للامتداد message.send لأن التنفيذ غير متداخل. بدلا من ذلك، executor.process يتم ربط امتداد المنفذ الهدف بامتداد message.send المنفذ المصدر. ينشئ هذا الارتباط مسارا قابلا للتتبع من خلال تنفيذ سير العمل دون الإشارة إلى تسلسل هرمي للاتصالات المتداخلة.

ينطبق نفس نهج الربط على edge_group.process الامتدادات، والتي ترتبط بامتدادات المصدر message.send لتتبع السببية. يدعم هذا سيناريوهات المروحة حيث تساهم امتدادات المصدر المتعددة في نطاق معالجة واحد.

حالة تسليم مجموعة Edge

تتضمن امتدادات معالجة مجموعة Edge سمات حالة التسليم التي تشير إلى نتيجة توجيه الرسائل عبر كل مجموعة حافة. edge_group.delivery_status يتم تعيين السمة إلى إحدى القيم التالية:

Status Description
delivered تم تسليم الرسالة إلى المنفذ الهدف.
dropped type mismatch لا يمكن للمنفذ الهدف معالجة نوع الرسالة.
dropped target mismatch حددت الرسالة هدفا لا يتطابق مع هذه الحافة.
dropped condition false تم تقييم شرط توجيه الحافة إلى خطأ.
exception حدث استثناء أثناء معالجة الحافة.
buffered تم تخزين الرسالة مؤقتا، في انتظار رسائل إضافية (fan-in).

edge_group.delivered توفر السمة المنطقية فحصا سريعا لمعرفة ما إذا تم تسليم الرسالة بنجاح.

تكوين بيانات تتبع الاستخدام

يمكن تمكين بيانات تتبع الاستخدام لسير العمل من خلال أسلوب الملحق WithOpenTelemetry على منشئ سير العمل. WorkflowTelemetryOptions توفر الفئة تحكما دقيقا في الامتدادات التي يتم إصدارها:

خيار Default Description
EnableSensitiveData false يتضمن المدخلات الأولية والمخرجات ومحتوى الرسالة في سمات النطاق.
DisableWorkflowBuild false تعطيل الامتدادات workflow.build .
DisableWorkflowRun false workflow.session التعطيل والامتداداتworkflow_invoke.
DisableExecutorProcess false تعطيل الامتدادات executor.process .
DisableEdgeGroupProcess false تعطيل الامتدادات edge_group.process .
DisableMessageSend false تعطيل الامتدادات message.send .

تحذير

يؤدي تمكين البيانات الحساسة إلى تضمين محتوى الرسائل الأولية ومدخلات المنفذ ومخرجات المنفذ في بيانات تتبع الاستخدام. قم بتمكين ذلك فقط في بيئات آمنة حيث تكون بيانات تتبع الاستخدام محمية بشكل مناسب.

يتم تمكين بيانات تتبع الاستخدام لسير العمل من خلال الوظيفة العمومية enable_instrumentation() . عند تمكين تقرير عن حالة النظام، يتم إصدار جميع نطاقات سير العمل تلقائيا. configure_otel_providers() يمكن استخدام الدالة لإعداد المصدرين للتتبعات والمقاييس والسجلات.

تحذير

راجع تكوين مسار بيانات تتبع الاستخدام للتأكد من حماية البيانات الحساسة بشكل مناسب عند تصدير التتبعات.

إمكانية مراقبة سير العمل

يمكن تمكين بيانات تتبع الاستخدام لسير العمل باستخدام WithTelemetry على منشئ سير العمل. استخدم حزمة تتبع OpenTelemetry لسير العمل لتوصيل الامتدادات بموفر OpenTelemetry.

تمكين تتبع سير العمل

import workflowotel "github.com/microsoft/agent-framework-go/workflow/observability/opentelemetry"

wf, err := workflow.NewBuilder(startExecutor).
    AddEdge(startExecutor, nextExecutor).
    WithTelemetry(
        workflowotel.New(workflowotel.Config{}),
        workflow.TelemetryOptions{EnableSensitiveData: true},
    ).
    Build()

TelemetryOptions يمكن تعطيل إنشاء/تشغيل سير العمل أو عملية المنفذ أو مجموعة الحافة أو نطاقات إرسال الرسائل، ويمكن أن تتضمن مدخلات ومخرجات متسلسلة عند EnableSensitiveData تعيينها.

مراقبة أحداث سير العمل

مراقبة تنفيذ سير العمل من خلال تدفقات الأحداث:

for evt := range run.NewEvents() {
    switch e := evt.(type) {
    case workflow.ExecutorCompletedEvent:
        log.Printf("Executor %s completed", e.ExecutorID)
    }
}

الخطوات التالية

  • Last updated on