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ü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.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ımlanan. Yürütücü kimliği span adına 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 yayılan.

İş 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 Bir iş akışı yürütme oturumunun ömrünü temsil eden dış span.
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 oluşturulur.

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 Uygulayıcının özgün tanımlayıcısı.
executor.type executor.process Yürütücü türünün 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).
Özellik Span(lar) Description
workflow.id workflow.build, workflow.session, workflow_invoke İş akışı başlatma yürütücüsünün kimliği.
workflow.name workflow.session, workflow_invoke Ayarlandığında iş akışı adı.
workflow.description workflow.session, workflow_invoke Ayarlandığında iş akışı açıklaması.
workflow.definition workflow.build İş akışı grafiğinin JSON tanımı.
session.id workflow.session, workflow_invoke İş akışı oturum tanımlayıcısı.
executor.id executor.process Yürütücü kimliği.
executor.implementation.id executor.process Yürütücü uygulama kimliği.
executor.input executor.process Giriş iletisi. Yalnızca hassas veriler etkinleştirildiğinde ayarlanır.
executor.output executor.process Çalıştırıcı çıktısı. Yalnızca hassas veriler etkinleştirildiğinde ayarlanır.
message.type executor.process İşlenen iletinin tür adı.
message.content message.send İleti içeriği. Yalnızca hassas veriler etkinleştirildiğinde ayarlanır.
message.source_id edge_group.process, message.send İletiyi gönderen yürütücü kimliği.
message.target_id edge_group.process, message.send Belirtildiği takdirde hedef yürütücünün kimliği.
edge_group.type edge_group.process İşlenmekte olan kenar grubu türü.
edge_group.delivered edge_group.process İletinin teslim edilip edilmediği.
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ı.
error.message Hatadaki herhangi bir yayılma alanı Özel durum iletisi.

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 başarısız olduğunda gönderilir.
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.
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.

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 kaynakedge_group.process aralıklara bağlı olan message.send 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.

İş akışı gözlemlenebilirliği

İş akışı telemetrisi, iş akışı oluşturucusunun üzerinde ile WithTelemetry etkinleştirilebilir. Span'leri OpenTelemetry sağlayıcınıza bağlamak için workflow OpenTelemetry izleyici paketini kullanın.

İş akışı izlemeyi etkinleştirme

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, iş akışı derleme/çalıştırma, yürütücü süreci, kenar grubu veya mesaj gönderme izlerini devre dışı bırakabilir ve EnableSensitiveData ayarlandığında serileştirilmiş girdileri ve çıktıları da içerebilir.

İş akışı olaylarını gözlemleme

Olay akışları aracılığıyla iş akışı yürütmeyi izleyin:

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

Sonraki Adımlar

  • Last updated on