Microsoft Agent Framework İş Akışları - Gözlemlenebilirlik

Gözlemlenebilirlik, yürütme sırasında iş akışlarının iç durumu ve davranışı hakkında içgörüler sağlar. Bu, iş akışlarını izlemeye ve hatalarını ayıklamaya yardımcı olan günlüğe kaydetme, metrikler ve izleme yeteneklerini içerir.

Tavsiye

Gözlemlenebilirlik, çerçeve genelindeki bir özelliktir ve iş akışlarıyla sınırlı değildir. Daha fazla bilgi için bkz. Gözlemlenebilirlik.

Standart GenAI telemetrisinin yanı sıra, Agent Framework İş Akışları iş akışı yürütme hakkında daha ayrıntılı içgörüler sağlamak için ek yayılma alanları, günlükler ve ölçümler yayar. Bu gözlemlenebilirlik özellikleri geliştiricilerin ileti akışını, yürütücülerin performansını ve oluşabilecek hataları anlamasına yardımcı olur.

Gözlemlenebilirliği Etkinleştirme

Uygulamalarınızda gözlemlenebilirliği etkinleştirme yönergeleri için lütfen Gözlemlenebilirliği Etkinleştirme bölümüne bakın.

Uygulamalarınızda gözlemlenebilirliği etkinleştirme yönergeleri için lütfen Gözlemlenebilirliği Etkinleştirme bölümüne bakın.

İş Akışı Aralıkları

İş akışı yürütme sırasında aşağıdaki span'lar oluşturulur:

Span Adı	Description
workflow.build	Her iş akışı derlemesi için yayınlanır.
workflow.session	Başlangıçtan durma veya hata oluşuna kadar iş akışı yürütmesinin tüm ömrünü temsil eden dış kapsam.
workflow_invoke	Her giriş-durdurma çevrimi için bir iş akışı oturumunda yayımlanır.
executor.process {executor_id}	Bir iletiyi işleyen her yürütücü için yayımlanan. Yürütücü kimliği span adına eklenir.
edge_group.process	Bir iletiyi işleyen her kenar grubu için yayılan.
message.send	Bir yürütücüden başka bir yürütücüye gönderilen her ileti için yayılan.

İş akışı yürütüldüğünde aşağıdaki span'lar oluşturulur:

Span Adı	Description
workflow.build	Her iş akışı yapılandırması için oluşturulan.
workflow.run	Her bir iş akışı yürütmesi için yayımlanır.
executor.process {executor_id}	Bir iletiyi işleyen her yürütücü için yayılan. Yürütücü kimliği, span adının sonuna eklenir.
edge_group.process {edge_group_type}	Bir iletiyi işleyen her kenar grubu için yayılan. Kenar grubu türü, span adına eklenir.
message.send	Bir yürütücüden başka bir yürütücüye gönderilen her ileti için oluşturulan.

Span Öznitelikleri

Spans, işlem hakkında ek bağlam sağlayan öznitelikleri taşır. İş akışı aralıklarında aşağıdaki öznitelikler ayarlanır:

Özellik	Span(lar)	Description
workflow.id	workflow.build, workflow.session	İş akışının benzersiz tanımlayıcısı.
workflow.name	workflow.session	İş akışının adı.
workflow.description	workflow.session	İş akışının açıklaması.
workflow.definition	workflow.build	İş akışı grafiğinin JSON tanımı.
session.id	workflow.session	Benzersiz oturum tanımlayıcısı.
executor.id	executor.process	Uygulayıcının özgün tanımlayıcısı.
executor.type	executor.process	Yürütücü türünün adı.
executor.input	executor.process	Giriş iletisi. Yalnızca hassas veriler etkinleştirildiğinde ayarlanır.
executor.output	executor.process	Yürütücü modülün çıkışı. Yalnızca hassas veriler etkinleştirildiğinde ayarlanır.
message.type	executor.process, message.send	İletinin tür adı.
message.content	message.send	İleti içeriği. Yalnızca hassas veriler etkinleştirildiğinde ayarlanır.
message.source_id	message.send	İletiyi gönderen yürütücü kimliği.
message.target_id	message.send	Belirtildiyse hedef yürütücü kimliği.
edge_group.type	edge_group.process	Kenar grubunun türü.
edge_group.delivered	edge_group.process	İletinin teslim edilip edilmediği (boolean).
edge_group.delivery_status	edge_group.process	Teslim sonucu (bkz . Edge Grup Teslim Durumu).
error.type	Hatadaki herhangi bir yayılma alanı	Özel durum türü adı.

Özellik	Span(lar)	Description
workflow.id	workflow.build, workflow.run	İş akışının benzersiz tanımlayıcısı.
workflow.name	workflow.run	İş akışının adı.
workflow.description	workflow.run	İş akışının açıklaması.
workflow.definition	workflow.build	İş akışı grafiğinin JSON tanımı.
workflow_builder.name	workflow.build	İş akışı oluşturucusunun adı.
workflow_builder.description	workflow.build	İş akışı oluşturucusunun açıklaması.
executor.id	executor.process	Yürütücünün benzersiz kimlik tanımlayıcısı.
executor.type	executor.process	Yürütücü tür adı.
message.type	executor.process, message.send	İletinin tür adı.
message.payload_type	executor.process	İleti yükünün veri türü.
message.destination_executor_id	message.send	Belirtildiyse hedef yürütücü kimliği.
message.source_id	edge_group.process	İletiyi gönderen yürütücü kimliği.
message.target_id	edge_group.process	Belirtildiyse hedef yürütücü kimliği.
edge_group.type	edge_group.process	Kenar grubunun türü.
edge_group.id	edge_group.process	Kenar grubunun benzersiz tanımlayıcısı.
edge_group.delivered	edge_group.process	İletinin teslim edilip edilmediği (boolean).
edge_group.delivery_status	edge_group.process	Teslim sonucu (bkz . Edge Grup Teslim Durumu).

Span Olayları

Span olayları, span'lara eklenen yapılandırılmış günlük girişleri olup her bir span içindeki önemli anların zaman çizelgesini sunar.

Olay Adı	Span(lar)	Description
build.started	workflow.build	Derleme işlemi başladığında gönderilir.
build.validation_completed	workflow.build	Derleme doğrulaması geçtiğinde gönderilir.
build.completed	workflow.build	Derleme başarıyla tamamlandığında gönderilir.
build.error	workflow.build	Derleme başarısız olduğunda gönderilir.
session.started	workflow.session	İş akışı oturumu başladığında yayılır.
session.completed	workflow.session	İş akışı oturumu tamamlandığında gönderilir.
session.error	workflow.session	bir iş akışı oturumu bir hatayla karşılaştığında yayılır.
workflow.started	workflow_invoke	bir iş akışı çağrısı başladığında gönderilir.
workflow.completed	workflow_invoke	bir iş akışı çağırma tamamlandığında gönderilir.
workflow.error	workflow_invoke	Bir iş akışı çağrısı bir hatayla karşılaştığında oluşturulur.

Olay Adı	Span(lar)	Description
build.started	workflow.build	Derleme işlemi başladığında gönderilir.
build.validation_completed	workflow.build	Derleme doğrulaması geçtiğinde gönderilir.
build.completed	workflow.build	Derleme başarıyla tamamlandığında gönderilir.
build.error	workflow.build	Derleme işlemi başarısız olduğunda yayınlanır.
workflow.started	workflow.run	Bir iş akışı çalıştırması başladığında tetiklenir.
workflow.completed	workflow.run	Bir iş akışı çalıştırması tamamlandığında tetiklenir.
workflow.error	workflow.run	Bir iş akışı çalıştırması bir hatayla karşılaştığında tetiklenir.

Spans arasındaki bağlantılar

Yürütücü başka bir yürütücüye ileti gönderdiğinde, message.send kapsamı, executor.process kapsamının alt öğesi olarak oluşturulur. Ancak, executor.process hedef yürütücünün dilimi iç içe olmadığındanmessage.send diliminin alt öğesi değildir. Bunun yerine, executor.process hedef yürütücüsünün aralığı, kaynak yürütücüsünün aralığına bağlanır. Bu bağlama, iç içe çağrı hiyerarşisini ima etmeden iş akışı yürütmesi aracılığıyla izlenebilir bir yol oluşturur.

Aynı bağlantı yaklaşımı, nedensellik izleme amacıyla kaynakmessage.send aralıklara bağlı olan edge_group.process aralıklar için de geçerlidir. Bu, birden çok kaynak aralığının tek bir işleme aralığına katkıda bulunduğu fan-in senaryolarını destekler.

Edge Grubu Teslim Durumu

Edge grubu işleme aralıkları, her kenar grubu aracılığıyla ileti yönlendirmenin sonucunu gösteren teslim durumu özniteliklerini içerir. edge_group.delivery_status özniteliği aşağıdaki değerlerden birine ayarlanır:

Statü	Description
delivered	İleti hedef yürütücüye teslim edildi.
dropped type mismatch	Hedef yürütücü ileti türünü işleyemiyor.
dropped target mismatch	İleti, bu kenarla eşleşmeyen bir hedef belirtti.
dropped condition false	Kenar yönlendirme koşulu false olarak değerlendirildi.
exception	Uç işleme sırasında bir istisna oluştu.
buffered	İleti arabelleğe alındı, ek iletiler bekleniyordu (fan-in).

boole özniteliği, edge_group.delivered iletinin başarıyla teslim edilip edilmediğine yönelik hızlı bir denetim sağlar.

Telemetri Yapılandırması

İş akışı telemetrisi, iş akışı oluşturucusunun WithOpenTelemetry uzantı yöntemi aracılığıyla etkinleştirilebilir. WorkflowTelemetryOptions sınıfı, hangi yayılma aralıklarının yayıldığı üzerinde ayrıntılı denetim sağlar:

Seçenek	Varsayılan	Description
EnableSensitiveData	false	Span özniteliklerinde ham girişler, çıkışlar ve ileti içeriği içerir.
DisableWorkflowBuild	false	workflow.build aralıklarını devre dışı bırakır.
DisableWorkflowRun	false	workflow.session ve workflow_invoke aralıklarını devre dışı bırakır.
DisableExecutorProcess	false	executor.process aralıklarını devre dışı bırakır.
DisableEdgeGroupProcess	false	edge_group.process aralıklarını devre dışı bırakır.
DisableMessageSend	false	message.send aralıklarını devre dışı bırakır.

Uyarı

Hassas verilerin etkinleştirilmesi ham ileti içeriğinin, yürütücü girişlerinin ve yürütücü çıkışlarının telemetriye eklenmesine neden olur. Bunu yalnızca telemetri verilerinin uygun şekilde korunduğu güvenli ortamlarda etkinleştirin.

İş akışı telemetrisi genel enable_instrumentation() işlev aracılığıyla etkinleştirilir. Enstrümantasyon etkinleştirildiğinde, tüm iş akışı dilimleri otomatik olarak yayılır. configure_otel_providers() İşlev, izlemeler, ölçümler ve günlükler için dışarı aktarmaları ayarlamak için kullanılabilir.

Uyarı

İzlemeleri dışarı aktarırken hassas verilerin uygun şekilde korunduğundan emin olmak için telemetri işlem hattı yapılandırmanızı gözden geçirin.

Sonraki Adımlar

• İş akışlarında durum yalıtımı hakkında bilgi edinin.
• İş akışlarını görselleştirmeyi öğrenin.